'\" t
.\" Title: git-fetch
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 01/13/2023
.\" Manual: Git Manual
.\" Source: Git 2.39.1
.\" Language: English
.\"
.TH "GIT\-FETCH" "1" "01/13/2023" "Git 2\&.39\&.1" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-fetch \- Download objects and refs from another repository
.SH "SYNOPSIS"
.sp
.nf
\fIgit fetch\fR [] [ [\&...]]
\fIgit fetch\fR []
\fIgit fetch\fR \-\-multiple [] [( | )\&...]
\fIgit fetch\fR \-\-all []
.fi
.sp
.SH "DESCRIPTION"
.sp
Fetch branches and/or tags (collectively, "refs") from one or more other repositories, along with the objects necessary to complete their histories\&. Remote\-tracking branches are updated (see the description of below for ways to control this behavior)\&.
.sp
By default, any tag that points into the histories being fetched is also fetched; the effect is to fetch tags that point at branches that you are interested in\&. This default behavior can be changed by using the \-\-tags or \-\-no\-tags options or by configuring remote\&.\&.tagOpt\&. By using a refspec that fetches tags explicitly, you can fetch tags that do not point into branches you are interested in as well\&.
.sp
\fIgit fetch\fR can fetch from either a single named repository or URL, or from several repositories at once if is given and there is a remotes\&. entry in the configuration file\&. (See \fBgit-config\fR(1))\&.
.sp
When no remote is specified, by default the \fBorigin\fR remote will be used, unless there\(cqs an upstream branch configured for the current branch\&.
.sp
The names of refs that are fetched, together with the object names they point at, are written to \fB\&.git/FETCH_HEAD\fR\&. This information may be used by scripts or other git commands, such as \fBgit-pull\fR(1)\&.
.SH "OPTIONS"
.PP
\-\-all
.RS 4
Fetch all remotes\&.
.RE
.PP
\-a, \-\-append
.RS 4
Append ref names and object names of fetched refs to the existing contents of
\fB\&.git/FETCH_HEAD\fR\&. Without this option old data in
\fB\&.git/FETCH_HEAD\fR
will be overwritten\&.
.RE
.PP
\-\-atomic
.RS 4
Use an atomic transaction to update local refs\&. Either all refs are updated, or on error, no refs are updated\&.
.RE
.PP
\-\-depth=
.RS 4
Limit fetching to the specified number of commits from the tip of each remote branch history\&. If fetching to a
\fIshallow\fR
repository created by
\fBgit clone\fR
with
\fB\-\-depth=\fR
option (see
\fBgit-clone\fR(1)), deepen or shorten the history to the specified number of commits\&. Tags for the deepened commits are not fetched\&.
.RE
.PP
\-\-deepen=
.RS 4
Similar to \-\-depth, except it specifies the number of commits from the current shallow boundary instead of from the tip of each remote branch history\&.
.RE
.PP
\-\-shallow\-since=
.RS 4
Deepen or shorten the history of a shallow repository to include all reachable commits after \&.
.RE
.PP
\-\-shallow\-exclude=
.RS 4
Deepen or shorten the history of a shallow repository to exclude commits reachable from a specified remote branch or tag\&. This option can be specified multiple times\&.
.RE
.PP
\-\-unshallow
.RS 4
If the source repository is complete, convert a shallow repository to a complete one, removing all the limitations imposed by shallow repositories\&.
.sp
If the source repository is shallow, fetch as much as possible so that the current repository has the same history as the source repository\&.
.RE
.PP
\-\-update\-shallow
.RS 4
By default when fetching from a shallow repository,
\fBgit fetch\fR
refuses refs that require updating \&.git/shallow\&. This option updates \&.git/shallow and accept such refs\&.
.RE
.PP
\-\-negotiation\-tip=
.RS 4
By default, Git will report, to the server, commits reachable from all local refs to find common commits in an attempt to reduce the size of the to\-be\-received packfile\&. If specified, Git will only report commits reachable from the given tips\&. This is useful to speed up fetches when the user knows which local ref is likely to have commits in common with the upstream ref being fetched\&.
.sp
This option may be specified more than once; if so, Git will report commits reachable from any of the given commits\&.
.sp
The argument to this option may be a glob on ref names, a ref, or the (possibly abbreviated) SHA\-1 of a commit\&. Specifying a glob is equivalent to specifying this option multiple times, one for each matching ref name\&.
.sp
See also the
\fBfetch\&.negotiationAlgorithm\fR
and
\fBpush\&.negotiate\fR
configuration variables documented in
\fBgit-config\fR(1), and the
\fB\-\-negotiate\-only\fR
option below\&.
.RE
.PP
\-\-negotiate\-only
.RS 4
Do not fetch anything from the server, and instead print the ancestors of the provided
\fB\-\-negotiation\-tip=*\fR
arguments, which we have in common with the server\&.
.sp
This is incompatible with
\fB\-\-recurse\-submodules=[yes|on\-demand]\fR\&. Internally this is used to implement the
\fBpush\&.negotiate\fR
option, see
\fBgit-config\fR(1)\&.
.RE
.PP
\-\-dry\-run
.RS 4
Show what would be done, without making any changes\&.
.RE
.PP
\-\-[no\-]write\-fetch\-head
.RS 4
Write the list of remote refs fetched in the
\fBFETCH_HEAD\fR
file directly under
\fB$GIT_DIR\fR\&. This is the default\&. Passing
\fB\-\-no\-write\-fetch\-head\fR
from the command line tells Git not to write the file\&. Under
\fB\-\-dry\-run\fR
option, the file is never written\&.
.RE
.PP
\-f, \-\-force
.RS 4
When
\fIgit fetch\fR
is used with
\fB:\fR
refspec it may refuse to update the local branch as discussed in the
\fB\fR
part below\&. This option overrides that check\&.
.RE
.PP
\-k, \-\-keep
.RS 4
Keep downloaded pack\&.
.RE
.PP
\-\-multiple
.RS 4
Allow several and arguments to be specified\&. No s may be specified\&.
.RE
.PP
\-\-[no\-]auto\-maintenance, \-\-[no\-]auto\-gc
.RS 4
Run
\fBgit maintenance run \-\-auto\fR
at the end to perform automatic repository maintenance if needed\&. (\fB\-\-[no\-]auto\-gc\fR
is a synonym\&.) This is enabled by default\&.
.RE
.PP
\-\-[no\-]write\-commit\-graph
.RS 4
Write a commit\-graph after fetching\&. This overrides the config setting
\fBfetch\&.writeCommitGraph\fR\&.
.RE
.PP
\-\-prefetch
.RS 4
Modify the configured refspec to place all refs into the
\fBrefs/prefetch/\fR
namespace\&. See the
\fBprefetch\fR
task in
\fBgit-maintenance\fR(1)\&.
.RE
.PP
\-p, \-\-prune
.RS 4
Before fetching, remove any remote\-tracking references that no longer exist on the remote\&. Tags are not subject to pruning if they are fetched only because of the default tag auto\-following or due to a \-\-tags option\&. However, if tags are fetched due to an explicit refspec (either on the command line or in the remote configuration, for example if the remote was cloned with the \-\-mirror option), then they are also subject to pruning\&. Supplying
\fB\-\-prune\-tags\fR
is a shorthand for providing the tag refspec\&.
.sp
See the PRUNING section below for more details\&.
.RE
.PP
\-P, \-\-prune\-tags
.RS 4
Before fetching, remove any local tags that no longer exist on the remote if
\fB\-\-prune\fR
is enabled\&. This option should be used more carefully, unlike
\fB\-\-prune\fR
it will remove any local references (local tags) that have been created\&. This option is a shorthand for providing the explicit tag refspec along with
\fB\-\-prune\fR, see the discussion about that in its documentation\&.
.sp
See the PRUNING section below for more details\&.
.RE
.PP
\-n, \-\-no\-tags
.RS 4
By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally\&. This option disables this automatic tag following\&. The default behavior for a remote may be specified with the remote\&.\&.tagOpt setting\&. See
\fBgit-config\fR(1)\&.
.RE
.PP
\-\-refetch
.RS 4
Instead of negotiating with the server to avoid transferring commits and associated objects that are already present locally, this option fetches all objects as a fresh clone would\&. Use this to reapply a partial clone filter from configuration or using
\fB\-\-filter=\fR
when the filter definition has changed\&. Automatic post\-fetch maintenance will perform object database pack consolidation to remove any duplicate objects\&.
.RE
.PP
\-\-refmap=
.RS 4
When fetching refs listed on the command line, use the specified refspec (can be given more than once) to map the refs to remote\-tracking branches, instead of the values of
\fBremote\&.*\&.fetch\fR
configuration variables for the remote repository\&. Providing an empty
\fB\fR
to the
\fB\-\-refmap\fR
option causes Git to ignore the configured refspecs and rely entirely on the refspecs supplied as command\-line arguments\&. See section on "Configured Remote\-tracking Branches" for details\&.
.RE
.PP
\-t, \-\-tags
.RS 4
Fetch all tags from the remote (i\&.e\&., fetch remote tags
\fBrefs/tags/*\fR
into local tags with the same name), in addition to whatever else would otherwise be fetched\&. Using this option alone does not subject tags to pruning, even if \-\-prune is used (though tags may be pruned anyway if they are also the destination of an explicit refspec; see
\fB\-\-prune\fR)\&.
.RE
.PP
\-\-recurse\-submodules[=yes|on\-demand|no]
.RS 4
This option controls if and under what conditions new commits of submodules should be fetched too\&. When recursing through submodules,
\fBgit fetch\fR
always attempts to fetch "changed" submodules, that is, a submodule that has commits that are referenced by a newly fetched superproject commit but are missing in the local submodule clone\&. A changed submodule can be fetched as long as it is present locally e\&.g\&. in
\fB$GIT_DIR/modules/\fR
(see
\fBgitsubmodules\fR(7)); if the upstream adds a new submodule, that submodule cannot be fetched until it is cloned e\&.g\&. by
\fBgit submodule update\fR\&.
.sp
When set to
\fIon\-demand\fR, only changed submodules are fetched\&. When set to
\fIyes\fR, all populated submodules are fetched and submodules that are both unpopulated and changed are fetched\&. When set to
\fIno\fR, submodules are never fetched\&.
.sp
When unspecified, this uses the value of
\fBfetch\&.recurseSubmodules\fR
if it is set (see
\fBgit-config\fR(1)), defaulting to
\fIon\-demand\fR
if unset\&. When this option is used without any value, it defaults to
\fIyes\fR\&.
.RE
.PP
\-j, \-\-jobs=
.RS 4
Number of parallel children to be used for all forms of fetching\&.
.sp
If the
\fB\-\-multiple\fR
option was specified, the different remotes will be fetched in parallel\&. If multiple submodules are fetched, they will be fetched in parallel\&. To control them independently, use the config settings
\fBfetch\&.parallel\fR
and
\fBsubmodule\&.fetchJobs\fR
(see
\fBgit-config\fR(1))\&.
.sp
Typically, parallel recursive and multi\-remote fetches will be faster\&. By default fetches are performed sequentially, not in parallel\&.
.RE
.PP
\-\-no\-recurse\-submodules
.RS 4
Disable recursive fetching of submodules (this has the same effect as using the
\fB\-\-recurse\-submodules=no\fR
option)\&.
.RE
.PP
\-\-set\-upstream
.RS 4
If the remote is fetched successfully, add upstream (tracking) reference, used by argument\-less
\fBgit-pull\fR(1)
and other commands\&. For more information, see
\fBbranch\&.\&.merge\fR
and
\fBbranch\&.\&.remote\fR
in
\fBgit-config\fR(1)\&.
.RE
.PP
\-\-submodule\-prefix=
.RS 4
Prepend to paths printed in informative messages such as "Fetching submodule foo"\&. This option is used internally when recursing over submodules\&.
.RE
.PP
\-\-recurse\-submodules\-default=[yes|on\-demand]
.RS 4
This option is used internally to temporarily provide a non\-negative default value for the \-\-recurse\-submodules option\&. All other methods of configuring fetch\(cqs submodule recursion (such as settings in
\fBgitmodules\fR(5)
and
\fBgit-config\fR(1)) override this option, as does specifying \-\-[no\-]recurse\-submodules directly\&.
.RE
.PP
\-u, \-\-update\-head\-ok
.RS 4
By default
\fIgit fetch\fR
refuses to update the head which corresponds to the current branch\&. This flag disables the check\&. This is purely for the internal use for
\fIgit pull\fR
to communicate with
\fIgit fetch\fR, and unless you are implementing your own Porcelain you are not supposed to use it\&.
.RE
.PP
\-\-upload\-pack
.RS 4
When given, and the repository to fetch from is handled by
\fIgit fetch\-pack\fR,
\fB\-\-exec=\fR
is passed to the command to specify non\-default path for the command run on the other end\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Pass \-\-quiet to git\-fetch\-pack and silence any other internally used git commands\&. Progress is not reported to the standard error stream\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be verbose\&.
.RE
.PP
\-\-progress
.RS 4
Progress status is reported on the standard error stream by default when it is attached to a terminal, unless \-q is specified\&. This flag forces progress status even if the standard error stream is not directed to a terminal\&.
.RE
.PP
\-o