From 5b696cb390385f4906df411be917ef0a7b92ebb7 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 6 Oct 2025 18:58:47 +0000 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-push.adoc | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'Documentation/git-push.adoc') diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 5f5408e2c0..2b7f7de9dd 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]] ------------------ -- cgit v1.3-5-g9baa From 3856d8937817c6815ecabaa3a927fc2e124e8155 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 6 Oct 2025 18:58:49 +0000 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-push.adoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'Documentation/git-push.adoc') diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 2b7f7de9dd..808e0380b2 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 -- cgit v1.3-5-g9baa From 6e1688f1f462d7a704bbcc1dae612488b7ac6e29 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 6 Oct 2025 18:58:50 +0000 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-push.adoc | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) (limited to 'Documentation/git-push.adoc') diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 808e0380b2..484aa9025e 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 @@ -702,6 +704,7 @@ a `git gc` command on the origin repository. include::transfer-data-leaks.adoc[] +[[CONFIGURATION]] CONFIGURATION ------------- -- cgit v1.3-5-g9baa From a72504fe051272227f4097e8d664a9b7d871ec25 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 6 Oct 2025 18:58:51 +0000 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-push.adoc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/git-push.adoc') diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 484aa9025e..f187fd5934 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. -- cgit v1.3-5-g9baa