Skip to content

Commit 1d9dcce

Browse files
gitstergitster
committed
Merge branch 'je/doc-push-upstream' into jch
* je/doc-push-upstream: 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
2 parents 2577ebf + 87999e2 commit 1d9dcce

File tree

2 files changed

+64
-23
lines changed

2 files changed

+64
-23
lines changed

‎Documentation/git-push.adoc‎

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -19,31 +19,34 @@ SYNOPSIS
1919
DESCRIPTION
2020
-----------
2121

22-
Updates remote refs using local refs, while sending objects
23-
necessary to complete the given refs.
22+
Updates one or more branches, tags, or other references in a remote
23+
repository from your local repository, and sends all necessary data
24+
that isn't already on the remote.
25+
26+
To decide which repository to push to, Git uses the `<repository>`
27+
argument (for example `git push dev`), then if that's not specified the
28+
upstream configuration for the current branch, and then defaults
29+
to `origin`.
30+
31+
To decide which branches, tags, or other refs to push, Git uses
32+
(in order of precedence):
33+
34+
1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
35+
or the `--all`, `--mirror`, or `--tags` options
36+
2. The `remote.*.push` configuration for the repository being pushed to
37+
3. The `push.default` configuration. The default is `push.default=simple`,
38+
which will push to a branch with the same name as the current branch.
39+
See the CONFIGURATION section below for more on `push.default`.
40+
41+
As a safety measure, `git push` may fail if you haven't set an upstream
42+
for the current branch, depending on what `push.default` is set to.
43+
See the UPSTREAM BRANCHES section below for more on how to set and
44+
use upstreams.
2445

2546
You can make interesting things happen to a repository
2647
every time you push into it, by setting up 'hooks' there. See
2748
documentation for linkgit:git-receive-pack[1].
2849

29-
When the command line does not specify where to push with the
30-
`<repository>` argument, `branch.*.remote` configuration for the
31-
current branch is consulted to determine where to push. If the
32-
configuration is missing, it defaults to 'origin'.
33-
34-
When the command line does not specify what to push with `<refspec>...`
35-
arguments or `--all`, `--mirror`, `--tags` options, the command finds
36-
the default `<refspec>` by consulting `remote.*.push` configuration,
37-
and if it is not found, honors `push.default` configuration to decide
38-
what to push (See linkgit:git-config[1] for the meaning of `push.default`).
39-
40-
When neither the command-line nor the configuration specifies what to
41-
push, the default behavior is used, which corresponds to the `simple`
42-
value for `push.default`: the current branch is pushed to the
43-
corresponding upstream branch, but as a safety measure, the push is
44-
aborted if the upstream branch does not have the same name as the
45-
local one.
46-
4750

4851
OPTIONS[[OPTIONS]]
4952
------------------

‎Documentation/urls-remotes.adoc‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,44 @@ git push uses:
9191
HEAD:refs/heads/<head>
9292
------------
9393

94-
95-
96-
94+
UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
95+
--------------------------------------
96+
97+
Branches in Git can optionally have an upstream remote branch.
98+
Git defaults to using the upstream branch for remote operations, for example:
99+
100+
* It's the default for `git pull` or `git fetch` with no arguments
101+
* It's the default for `git push` with no arguments, with some exceptions.
102+
For example, you can use the `branch.<name>.pushRemote` option to push
103+
to a different remote than you pull from, and by default with
104+
`push.default=simple` the upstream branch you configure must have
105+
the same name.
106+
* Various commands, including `git checkout` and `git status`, will
107+
show you how many commits have been added to your current branch and
108+
the upstream since you forked from it, for example "Your branch and
109+
'origin/main' have diverged, and have 2 and 3 different commits each
110+
respectively"
111+
112+
The upstream is stored in `.git/config`, in the "remote" and "merge"
113+
fields. For example, if `main`'s upstream is `origin/main`:
114+
115+
[branch "main"]
116+
remote = origin
117+
merge = refs/heads/main
118+
119+
You can set an upstream branch explicitly with
120+
`git push --set-upstream <remote> <branch>` or `git branch --track`,
121+
but Git will often automatically set the upstream for you, for example:
122+
123+
* When you clone a repository, Git will automatically set the upstream
124+
for the default branch.
125+
* If you have the `push.autoSetupRemote` configuration option set,
126+
`git push` will automatically set the upstream the first time you push
127+
a branch.
128+
* Checking out a remote-tracking branch with `git checkout <branch>`
129+
will automatically create a local branch with that name and set
130+
the upstream to the remote branch.
131+
132+
[NOTE]
133+
Upstream branches are sometimes referred to as "tracking information",
134+
as in "set the branch's tracking information".

0 commit comments

Comments
 (0)