From f7316a66d36f39ed9e5be7a3ce0ecd7b71430ff5 Mon Sep 17 00:00:00 2001 From: Jean-Noël Avila Date: Wed, 19 Nov 2025 21:40:04 +0000 Subject: doc: convert git push to synopsis style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- Documentation/config/push.adoc | 113 ++++++++--------- Documentation/git-push.adoc | 267 ++++++++++++++++++++++------------------- 2 files changed, 201 insertions(+), 179 deletions(-) diff --git a/Documentation/config/push.adoc b/Documentation/config/push.adoc index 0acbbea18a..d9112b2260 100644 --- a/Documentation/config/push.adoc +++ b/Documentation/config/push.adoc @@ -1,15 +1,15 @@ -push.autoSetupRemote:: - If set to "true" assume `--set-upstream` on default push when no +`push.autoSetupRemote`:: + If set to `true` assume `--set-upstream` on default push when no upstream tracking exists for the current branch; this option - takes effect with push.default options 'simple', 'upstream', - and 'current'. It is useful if by default you want new branches + takes effect with `push.default` options `simple`, `upstream`, + and `current`. It is useful if by default you want new branches to be pushed to the default remote (like the behavior of - 'push.default=current') and you also want the upstream tracking + `push.default=current`) and you also want the upstream tracking to be set. Workflows most likely to benefit from this option are - 'simple' central workflows where all branches are expected to + `simple` central workflows where all branches are expected to have the same name on the remote. -push.default:: +`push.default`:: Defines the action `git push` should take if no refspec is given (whether from the command-line, config, or elsewhere). Different values are well-suited for @@ -18,24 +18,28 @@ push.default:: `upstream` is probably what you want. Possible values are: + -- - -* `nothing` - do not push anything (error out) unless a refspec is - given. This is primarily meant for people who want to - avoid mistakes by always being explicit. - -* `current` - push the current branch to update a branch with the same - name on the receiving end. Works in both central and non-central - workflows. - -* `upstream` - push the current branch back to the branch whose - changes are usually integrated into the current branch (which is - called `@{upstream}`). This mode only makes sense if you are - pushing to the same repository you would normally pull from - (i.e. central workflow). - -* `tracking` - This is a deprecated synonym for `upstream`. - -* `simple` - push the current branch with the same name on the remote. +`nothing`;; +do not push anything (error out) unless a refspec is +given. This is primarily meant for people who want to +avoid mistakes by always being explicit. + +`current`;; +push the current branch to update a branch with the same +name on the receiving end. Works in both central and non-central +workflows. + +`upstream`;; +push the current branch back to the branch whose +changes are usually integrated into the current branch (which is +called `@{upstream}`). This mode only makes sense if you are +pushing to the same repository you would normally pull from +(i.e. central workflow). + +`tracking`;; +this is a deprecated synonym for `upstream`. + +`simple`;; +push the current branch with the same name on the remote. + If you are working on a centralized workflow (pushing to the same repository you pull from, which is typically `origin`), then you need to configure an upstream @@ -44,16 +48,17 @@ branch with the same name. This mode is the default since Git 2.0, and is the safest option suited for beginners. -* `matching` - push all branches having the same name on both ends. - This makes the repository you are pushing to remember the set of - branches that will be pushed out (e.g. if you always push 'maint' - and 'master' there and no other branches, the repository you push - to will have these two branches, and your local 'maint' and - 'master' will be pushed there). +`matching`;; +push all branches having the same name on both ends. +This makes the repository you are pushing to remember the set of +branches that will be pushed out (e.g. if you always push `maint` +and `master` there and no other branches, the repository you push +to will have these two branches, and your local `maint` and +`master` will be pushed there). + To use this mode effectively, you have to make sure _all_ the branches you would push out are ready to be pushed out before -running 'git push', as the whole point of this mode is to allow you +running `git push`, as the whole point of this mode is to allow you to push all of the branches in one go. If you usually finish work on only one branch and push out the result, while other branches are unfinished, this mode is not for you. Also this mode is not @@ -66,24 +71,24 @@ new default). -- -push.followTags:: +`push.followTags`:: If set to true, enable `--follow-tags` option by default. You may override this configuration at time of push by specifying `--no-follow-tags`. -push.gpgSign:: - May be set to a boolean value, or the string 'if-asked'. A true +`push.gpgSign`:: + May be set to a boolean value, or the string `if-asked`. A true value causes all pushes to be GPG signed, as if `--signed` is - passed to linkgit:git-push[1]. The string 'if-asked' causes + passed to linkgit:git-push[1]. The string `if-asked` causes pushes to be signed if the server supports it, as if - `--signed=if-asked` is passed to 'git push'. A false value may + `--signed=if-asked` is passed to `git push`. A false value may override a value from a lower-priority config file. An explicit command-line flag always overrides this config option. -push.pushOption:: +`push.pushOption`:: When no `--push-option=