From 4811ce1c8621babcdfe12510fc581a28863bfb95 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Thu, 11 Sep 2025 15:51:06 -0400 Subject: [PATCH 1/5] doc: git-push: clarify intro From user feedback, 5 users are unsure what "ref" and/or "objects" means in this context. 3 users said they don't know what "complete the refs" means. Many users also commented that receive hooks do not seem like the most important thing to know about `git push`, and that this information should not be the second sentence in the man page. Use more familiar language to make it more accessible to users who do not know what a "ref" is and move the "hooks" comment to the end. Signed-off-by: Julia Evans --- Documentation/git-push.adoc | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index d1978650d60a7c..25d972f248f5c7 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -19,12 +19,9 @@ SYNOPSIS DESCRIPTION ----------- -Updates remote refs using local refs, while sending objects -necessary to complete the given refs. - -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]. +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. When the command line does not specify where to push with the `` argument, `branch.*.remote` configuration for the @@ -44,6 +41,10 @@ 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. +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]. + OPTIONS[[OPTIONS]] ------------------ From 10a9718421aa842573a2ba1ecf58d2cc46b5edd9 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Fri, 12 Sep 2025 10:58:16 -0400 Subject: [PATCH 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch From user feedback: one user mentioned that they don't know what the term "upstream branch" means. As far as I can tell, the most complete description is under the `--track` option in `git branch`. Upstreams are an important concept in Git and the `git branch` man page is not an obvious place for that information to live. There's also a very terse description of "upstream branch" in the glossary that's missing a lot of key information, like the fact that the upstream is used by `git status` and `git pull`, as well as a description in `git-config` in `branch..remote` which doesn't explain the relationship to `git status` either. Since the `git pull`, `git push`, and `git fetch` man pages already include sections on REMOTES and the syntax for URLs, add a section on UPSTREAM BRANCHES to `urls-remotes.adoc`. In the new UPSTREAM BRANCHES section, cover the various ways that upstreams branches are automatically set in Git, since users may mistakenly think that their branch does not have an upstream branch if they didn't explicitly set one. A terminology note: Git uses two terms for this concept: - "tracking" as in "the tracking information for the 'foo' branch" or the `--track` option to `git branch` - "upstream" or "upstream branch", as in `git push --set-upstream`. This term is also used in the `git rebase` man page to refer to the first argument to `git rebase`, as well as in `git pull` to refer to the branch which is going to be merged into the current branch ("merge the upstream branch into the current branch") Use "upstream branch" as a heading for this concept even though the term "upstream branch" is not always used strictly in the sense of "the tracking information for the current branch". "Upstream" is used much more often than "tracking" in the Git docs to refer to this concept and the goal is to help users understand the docs. Signed-off-by: Julia Evans --- Documentation/urls-remotes.adoc | 42 +++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc index 9b101511988471..57b1646d3e2a4e 100644 --- a/Documentation/urls-remotes.adoc +++ b/Documentation/urls-remotes.adoc @@ -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..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 ` +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 ` + 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". From 336023fbf14b15dd473fc02ff25bedc43ea0ea7a Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 25 Aug 2025 10:33:15 -0400 Subject: [PATCH 3/5] doc: git-push: clarify "where to push" It's not obvious that "`branch.*.remote` configuration"` refers to the upstream, so say "upstream" instead. The sentence is also quite hard to parse right now, use "defaults to" to simplify it. Signed-off-by: Julia Evans --- Documentation/git-push.adoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 25d972f248f5c7..acdf25e5cdbcdb 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -23,10 +23,8 @@ 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. -When the command line does not specify where to push with the -`` argument, `branch.*.remote` configuration for the -current branch is consulted to determine where to push. If the -configuration is missing, it defaults to 'origin'. +The `` argument defaults to the upstream for the current branch, +or `origin` if there's no configured upstream. When the command line does not specify what to push with `...` arguments or `--all`, `--mirror`, `--tags` options, the command finds From 8e82c508f6104d763fa05b74ebf8316010265ff0 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Thu, 11 Sep 2025 16:01:11 -0400 Subject: [PATCH 4/5] doc: git-push: clarify "what to push" From user feedback: 6 users says they found the "what to push" paragraphs confusing, for many different reasons, including: * what does "..." in ... mean? * "consult XXX configuration" is hard to parse * it refers to the `git-config` man page even though the config information for `git push` is included in this man page under CONFIGURATION * the default ("push to a branch with the same name") is what they use 99% of the time, they would have expected it to appear earlier instead of at the very end * not understanding what the term "upstream" means in Git ("are branches tracked by some system besides their names?"") Also, the current explanation of `push.default=simple` ("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.") is not accurate: `push.default=simple` does not always require you to set a corresponding upstream branch. Address all of these by * using a numbered "in order of precedence" list * giving a more accurate explanation of how `push.default=simple` works * giving a little bit of context around "upstream branch": it's something that you may have to set explicitly * referring to the new UPSTREAM BRANCHES section The default behaviour is still discussed pretty late but it should be easier to skim now to get to the relevant information. In "`git push` may fail if...", I'm intentionally being vague about what exactly `git push` does, because (as discussed on the mailing list) the behaviour of `push.default=simple` is very confusing, perhaps broken, and certainly not worth trying to explain in an introductory context. `push.default.simple` sometimes requires you to set an upstream and sometimes doesn't and the exact conditions under which it does/doesn't are hard to describe. Signed-off-by: Julia Evans --- Documentation/git-push.adoc | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index acdf25e5cdbcdb..aa01efcc0a93e2 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -26,18 +26,20 @@ that isn't already on the remote. The `` argument defaults to the upstream for the current branch, or `origin` if there's no configured upstream. -When the command line does not specify what to push with `...` -arguments or `--all`, `--mirror`, `--tags` options, the command finds -the default `` 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. +To decide which branches, tags, or other refs to push, Git uses +(in order of precedence): + +1. The `` 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 <> 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 <> 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 @@ -696,6 +698,7 @@ a `git gc` command on the origin repository. include::transfer-data-leaks.adoc[] +[[CONFIGURATION]] CONFIGURATION ------------- From ddeb8ecabe4ab30111b749dab3cb898ef41b4383 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 30 Sep 2025 15:05:28 -0400 Subject: [PATCH 5/5] doc: git-push: Add explanation of `git push origin main` What happens if you run `git push` without any arguments is actually extremely complex to explain, as discussed in the previous commit. But it's very easy to explain what `git push ` does, so start the man page by explaining what that does. The hope is that someone could just stop reading the man page here and never learn anything else about `git push`, and that would be fine. Signed-off-by: Julia Evans --- Documentation/git-push.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index aa01efcc0a93e2..36bf1cc43804cd 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -23,6 +23,10 @@ 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 `. +`git push origin main` will push the local `main` branch to the `main` +branch on the remote named `origin`. + The `` argument defaults to the upstream for the current branch, or `origin` if there's no configured upstream.