Merge branch 'je/doc-push-upstream' into jch
Documentation updates. * je/doc-push-upstream: doc: git-push: add explanation of `git push origin main` doc: git-push: clarify "what to push" doc: git-push: clarify "where to push" doc: add an UPSTREAM BRANCHES section to pull/push/fetch doc: git-push: clarify intro
Junio C Hamano
commit
16548595a8
|
|
@ -19,31 +19,36 @@ SYNOPSIS
|
|||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Updates remote refs using local refs, while sending objects
|
||||
necessary to complete the given refs.
|
||||
Updates one or more branches, tags, or other references in a remote
|
||||
repository from your local repository, and sends all necessary data
|
||||
that isn't already on the remote.
|
||||
|
||||
The simplest way to push is `git push <remote> <branch>`.
|
||||
`git push origin main` will push the local `main` branch to the `main`
|
||||
branch on the remote named `origin`.
|
||||
|
||||
The `<repository>` argument defaults to the upstream for the current branch,
|
||||
or `origin` if there's no configured upstream.
|
||||
|
||||
To decide which branches, tags, or other refs to push, Git uses
|
||||
(in order of precedence):
|
||||
|
||||
1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
|
||||
or the `--all`, `--mirror`, or `--tags` options
|
||||
2. The `remote.*.push` configuration for the repository being pushed to
|
||||
3. The `push.default` configuration. The default is `push.default=simple`,
|
||||
which will push to a branch with the same name as the current branch.
|
||||
See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
|
||||
|
||||
`git push` may fail if you haven't set an upstream for the current branch,
|
||||
depending on what `push.default` is set to.
|
||||
See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more
|
||||
on how to set and use upstreams.
|
||||
|
||||
You can make interesting things happen to a repository
|
||||
every time you push into it, by setting up 'hooks' there. See
|
||||
documentation for linkgit:git-receive-pack[1].
|
||||
|
||||
When the command line does not specify where to push with the
|
||||
`<repository>` argument, `branch.*.remote` configuration for the
|
||||
current branch is consulted to determine where to push. If the
|
||||
configuration is missing, it defaults to 'origin'.
|
||||
|
||||
When the command line does not specify what to push with `<refspec>...`
|
||||
arguments or `--all`, `--mirror`, `--tags` options, the command finds
|
||||
the default `<refspec>` by consulting `remote.*.push` configuration,
|
||||
and if it is not found, honors `push.default` configuration to decide
|
||||
what to push (See linkgit:git-config[1] for the meaning of `push.default`).
|
||||
|
||||
When neither the command-line nor the configuration specifies what to
|
||||
push, the default behavior is used, which corresponds to the `simple`
|
||||
value for `push.default`: the current branch is pushed to the
|
||||
corresponding upstream branch, but as a safety measure, the push is
|
||||
aborted if the upstream branch does not have the same name as the
|
||||
local one.
|
||||
|
||||
|
||||
OPTIONS[[OPTIONS]]
|
||||
------------------
|
||||
|
|
@ -710,6 +715,7 @@ a `git gc` command on the origin repository.
|
|||
|
||||
include::transfer-data-leaks.adoc[]
|
||||
|
||||
[[CONFIGURATION]]
|
||||
CONFIGURATION
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -92,5 +92,47 @@ git push uses:
|
|||
------------
|
||||
|
||||
|
||||
[[UPSTREAM-BRANCHES]]
|
||||
UPSTREAM BRANCHES
|
||||
-----------------
|
||||
|
||||
Branches in Git can optionally have an upstream remote branch.
|
||||
Git defaults to using the upstream branch for remote operations, for example:
|
||||
|
||||
* It's the default for `git pull` or `git fetch` with no arguments.
|
||||
* It's the default for `git push` with no arguments, with some exceptions.
|
||||
For example, you can use the `branch.<name>.pushRemote` option to push
|
||||
to a different remote than you pull from, and by default with
|
||||
`push.default=simple` the upstream branch you configure must have
|
||||
the same name.
|
||||
* Various commands, including `git checkout` and `git status`, will
|
||||
show you how many commits have been added to your current branch and
|
||||
the upstream since you forked from it, for example "Your branch and
|
||||
'origin/main' have diverged, and have 2 and 3 different commits each
|
||||
respectively".
|
||||
|
||||
The upstream is stored in `.git/config`, in the "remote" and "merge"
|
||||
fields. For example, if `main`'s upstream is `origin/main`:
|
||||
|
||||
------------
|
||||
[branch "main"]
|
||||
remote = origin
|
||||
merge = refs/heads/main
|
||||
------------
|
||||
|
||||
You can set an upstream branch explicitly with
|
||||
`git push --set-upstream <remote> <branch>`
|
||||
but Git will often automatically set the upstream for you, for example:
|
||||
|
||||
* When you clone a repository, Git will automatically set the upstream
|
||||
for the default branch.
|
||||
* If you have the `push.autoSetupRemote` configuration option set,
|
||||
`git push` will automatically set the upstream the first time you push
|
||||
a branch.
|
||||
* Checking out a remote-tracking branch with `git checkout <branch>`
|
||||
will automatically create a local branch with that name and set
|
||||
the upstream to the remote branch.
|
||||
|
||||
[NOTE]
|
||||
Upstream branches are sometimes referred to as "tracking information",
|
||||
as in "set the branch's tracking information".
|
||||
|
|
|
|||
Loading…
Reference in New Issue