git/Documentation/git-push.adoc, branch jch

push: support pushing to a remote group

2026-03-25T19:35:16Z

`git fetch` accepts a remote group name (configured via `remotes.` in config) and fetches from each member remote. `git push` has no equivalent — it only accepts a single remote name. Teach `git push` to resolve its repository argument through `add_remote_or_group()`, which was made public in the previous patch, so that a user can push to all remotes in a group with: git push When the argument resolves to a single remote, the behaviour is identical to before. When it resolves to a group, each member remote is pushed in sequence. The group push path rebuilds the refspec list (`rs`) from scratch for each member remote so that per-remote push mappings configured via `remote..push` are resolved correctly against each specific remote. Without this, refspec entries would accumulate across iterations and each subsequent remote would receive a growing list of duplicated entries. Mirror detection (`remote->mirror`) is also evaluated per remote using a copy of the flags, so that a mirror remote in the group cannot set TRANSPORT_PUSH_FORCE on subsequent non-mirror remotes in the same group. Suggested-by: Junio C Hamano Signed-off-by: Usman Akinyemi Signed-off-by: Junio C Hamano

doc: convert git push to synopsis style

2025-11-19T23:00:45Z

- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use __ instead of in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

Merge branch 'je/doc-push-upstream'

2025-10-14T19:56:09Z

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

doc: git-push: add explanation of `git push origin main`

2025-10-06T21:30:34Z

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

doc: git-push: clarify "what to push"

2025-10-06T21:29:49Z

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

doc: git-push: clarify "where to push"

2025-10-06T21:29:49Z

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

doc: git-push: clarify intro

2025-10-06T21:29:48Z

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

doc: git-push: rewrite refspec specification

2025-09-24T19:29:34Z

From user feedback, there was a request for examples, as well as a comment that one person found "If git push [] without any argument is set to update some ref at the destination with with remote..push configuration variable..." impossible to understand. To make the section easier to navigate, create a list of every possible refspec form, with examples for each form as well as 2 forms which were previously missing (patterns and negative refspecs). Made a few changes to use more familiar language, but ultimately refspecs are a pretty advanced feature so I've mostly left the terminology alone. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano

doc: git-push: create PUSH RULES section

2025-09-24T19:29:34Z

Right now the rules for when a `git push` is allowed are buried at the bottom of the description of ``. Put them in their own section so that we can reference them from `--force` and give some context for why they exist. Having the "PUSH RULES" section also lets us be a little bit more specific with the rule in `--force`: we can just focus on the rule for pushing for a branch (which is likely the one that's most relevant) and leave the details about what happens when you push to a tag or a ref that isn't a branch to the later section. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano

doc: check for absence of the form --[no-]parameter

2025-08-11T21:16:04Z

For better searchability, this commit adds a check to ensure that parameters expressed in the form of `--[no-]parameter` are not used in the documentation. In the place of such parameters, the documentation should list two separate parameters: `--parameter` and `--no-parameter`. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano