Skip to content

doc: convert fetch pull push to synopsis style #2002

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

doc: convert fetch pull push to synopsis style #2002

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
397f56d
doc: convert git fetch to synopsis style
jnavila Nov 3, 2025
5b1e64b
doc: convert git pull to synopsis style
jnavila Nov 7, 2025
e5526ea
doc: convert git push to synopsis style
jnavila Nov 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions Documentation/config/fetch.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
fetch.recurseSubmodules::
`fetch.recurseSubmodules`::
This option controls whether `git fetch` (and the underlying fetch
in `git pull`) will recursively fetch into populated submodules.
This option can be set either to a boolean value or to 'on-demand'.
This option can be set either to a boolean value or to `on-demand`.
Setting it to a boolean changes the behavior of fetch and pull to
recurse unconditionally into submodules when set to true or to not
recurse at all when set to false. When set to 'on-demand', fetch and
recurse at all when set to false. When set to `on-demand`, fetch and
pull will only recurse into a populated submodule when its
superproject retrieves a commit that updates the submodule's
reference.
Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
Defaults to `on-demand`, or to the value of `submodule.recurse` if set.

fetch.fsckObjects::
`fetch.fsckObjects`::
If it is set to true, git-fetch-pack will check all fetched
objects. See `transfer.fsckObjects` for what's
checked. Defaults to false. If not set, the value of
checked. Defaults to `false`. If not set, the value of
`transfer.fsckObjects` is used instead.

fetch.fsck.<msg-id>::
`fetch.fsck.<msg-id>`::
Acts like `fsck.<msg-id>`, but is used by
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
the `fsck.<msg-id>` documentation for details.

fetch.fsck.skipList::
`fetch.fsck.skipList`::
Acts like `fsck.skipList`, but is used by
linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
the `fsck.skipList` documentation for details.

fetch.unpackLimit::
`fetch.unpackLimit`::
If the number of objects fetched over the Git native
transfer is below this
limit, then the objects will be unpacked into loose object
Expand All @@ -37,54 +37,54 @@ fetch.unpackLimit::
especially on slow filesystems. If not set, the value of
`transfer.unpackLimit` is used instead.

fetch.prune::
`fetch.prune`::
If true, fetch will automatically behave as if the `--prune`
option was given on the command line. See also `remote.<name>.prune`
and the PRUNING section of linkgit:git-fetch[1].

fetch.pruneTags::
`fetch.pruneTags`::
If true, fetch will automatically behave as if the
`refs/tags/*:refs/tags/*` refspec was provided when pruning,
if not set already. This allows for setting both this option
and `fetch.prune` to maintain a 1=1 mapping to upstream
refs. See also `remote.<name>.pruneTags` and the PRUNING
section of linkgit:git-fetch[1].

fetch.all::
`fetch.all`::
If true, fetch will attempt to update all available remotes.
This behavior can be overridden by passing `--no-all` or by
explicitly specifying one or more remote(s) to fetch from.
Defaults to false.
Defaults to `false`.

fetch.output::
`fetch.output`::
Control how ref update status is printed. Valid values are
`full` and `compact`. Default value is `full`. See the
OUTPUT section in linkgit:git-fetch[1] for details.

fetch.negotiationAlgorithm::
`fetch.negotiationAlgorithm`::
Control how information about the commits in the local repository
is sent when negotiating the contents of the packfile to be sent by
the server. Set to "consecutive" to use an algorithm that walks
over consecutive commits checking each one. Set to "skipping" to
the server. Set to `consecutive` to use an algorithm that walks
over consecutive commits checking each one. Set to `skipping` to
use an algorithm that skips commits in an effort to converge
faster, but may result in a larger-than-necessary packfile; or set
to "noop" to not send any information at all, which will almost
to `noop` to not send any information at all, which will almost
certainly result in a larger-than-necessary packfile, but will skip
the negotiation step. Set to "default" to override settings made
the negotiation step. Set to `default` to override settings made
previously and use the default behaviour. The default is normally
"consecutive", but if `feature.experimental` is true, then the
default is "skipping". Unknown values will cause 'git fetch' to
`consecutive`, but if `feature.experimental` is `true`, then the
default is `skipping`. Unknown values will cause `git fetch` to
error out.
+
See also the `--negotiate-only` and `--negotiation-tip` options to
linkgit:git-fetch[1].

fetch.showForcedUpdates::
Set to false to enable `--no-show-forced-updates` in
`fetch.showForcedUpdates`::
Set to `false` to enable `--no-show-forced-updates` in
linkgit:git-fetch[1] and linkgit:git-pull[1] commands.
Defaults to true.
Defaults to `true`.

fetch.parallel::
`fetch.parallel`::
Specifies the maximal number of fetch operations to be run in parallel
at a time (submodules, or remotes when the `--multiple` option of
linkgit:git-fetch[1] is in effect).
Expand All @@ -94,16 +94,16 @@ A value of 0 will give some reasonable default. If unset, it defaults to 1.
For submodules, this setting can be overridden using the `submodule.fetchJobs`
config setting.

fetch.writeCommitGraph::
`fetch.writeCommitGraph`::
Set to true to write a commit-graph after every `git fetch` command
that downloads a pack-file from a remote. Using the `--split` option,
most executions will create a very small commit-graph file on top of
the existing commit-graph file(s). Occasionally, these files will
merge and the write may take longer. Having an updated commit-graph
file helps performance of many Git commands, including `git merge-base`,
`git push -f`, and `git log --graph`. Defaults to false.
`git push -f`, and `git log --graph`. Defaults to `false`.

fetch.bundleURI::
`fetch.bundleURI`::
This value stores a URI for downloading Git object data from a bundle
URI before performing an incremental fetch from the origin Git server.
This is similar to how the `--bundle-uri` option behaves in
Expand All @@ -115,9 +115,9 @@ If you modify this value and your repository has a `fetch.bundleCreationToken`
value, then remove that `fetch.bundleCreationToken` value before fetching from
the new bundle URI.

fetch.bundleCreationToken::
`fetch.bundleCreationToken`::
When using `fetch.bundleURI` to fetch incrementally from a bundle
list that uses the "creationToken" heuristic, this config value
list that uses the "`creationToken`" heuristic, this config value
stores the maximum `creationToken` value of the downloaded bundles.
This value is used to prevent downloading bundles in the future
if the advertised `creationToken` is not strictly larger than this
Expand Down
113 changes: 59 additions & 54 deletions Documentation/config/push.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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=<option>` argument is given from the
command line, `git push` behaves as if each <value> of
this variable is given as `--push-option=<value>`.
command line, `git push` behaves as if each _<option>_ of
this variable is given as `--push-option=<option>`.
+
This is a multi-valued variable, and an empty value can be used in a
higher priority configuration file (e.g. `.git/config` in a
Expand All @@ -109,26 +114,26 @@ This will result in only b (a and c are cleared).

----
push.recurseSubmodules::
May be "check", "on-demand", "only", or "no", with the same behavior
as that of "push --recurse-submodules".
If not set, 'no' is used by default, unless 'submodule.recurse' is
set (in which case a 'true' value means 'on-demand').
`push.recurseSubmodules`::
May be `check`, `on-demand`, `only`, or `no`, with the same behavior
as that of `push --recurse-submodules`.
If not set, `no` is used by default, unless `submodule.recurse` is
set (in which case a `true` value means `on-demand`).
push.useForceIfIncludes::
If set to "true", it is equivalent to specifying
`push.useForceIfIncludes`::
If set to `true`, it is equivalent to specifying
`--force-if-includes` as an option to linkgit:git-push[1]
in the command line. Adding `--no-force-if-includes` at the
time of push overrides this configuration setting.
push.negotiate::
If set to "true", attempt to reduce the size of the packfile
`push.negotiate`::
If set to `true`, attempt to reduce the size of the packfile
sent by rounds of negotiation in which the client and the
server attempt to find commits in common. If "false", Git will
server attempt to find commits in common. If `false`, Git will
rely solely on the server's ref advertisement to find commits
in common.
push.useBitmaps::
If set to "false", disable use of bitmaps for "git push" even if
`pack.useBitmaps` is "true", without preventing other git operations
from using bitmaps. Default is true.
`push.useBitmaps`::
If set to `false`, disable use of bitmaps for `git push` even if
`pack.useBitmaps` is `true`, without preventing other git operations
from using bitmaps. Default is `true`.
Loading
Loading