Git - git-fetch Documentation (2024)

Fetch all remotes.

Append ref names and object names of fetched refs to theexisting contents of .git/FETCH_HEAD. Without thisoption old data in .git/FETCH_HEAD will be overwritten.

Use an atomic transaction to update local refs. Either all refs areupdated, or on error, no refs are updated.

Limit fetching to the specified number of commits from the tip ofeach remote branch history. If fetching to a shallow repositorycreated by git clone with --depth=<depth> option (seegit-clone[1]), deepen or shorten the history to the specifiednumber of commits. Tags for the deepened commits are not fetched.

Similar to --depth, except it specifies the number of commitsfrom the current shallow boundary instead of from the tip ofeach remote branch history.

Deepen or shorten the history of a shallow repository toinclude all reachable commits after <date>.

Deepen or shorten the history of a shallow repository toexclude commits reachable from a specified remote branch or tag.This option can be specified multiple times.

If the source repository is complete, convert a shallowrepository to a complete one, removing all the limitationsimposed by shallow repositories.

If the source repository is shallow, fetch as much as possible so thatthe current repository has the same history as the source repository.

By default when fetching from a shallow repository,git fetch refuses refs that require updating.git/shallow. This option updates .git/shallow and accept suchrefs.

By default, Git will report, to the server, commits reachablefrom all local refs to find common commits in an attempt toreduce 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 whichlocal ref is likely to have commits in common with theupstream ref being fetched.

This option may be specified more than once; if so, Git will reportcommits reachable from any of the given commits.

The argument to this option may be a glob on ref names, a ref, or the (possiblyabbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifyingthis option multiple times, one for each matching ref name.

See also the fetch.negotiationAlgorithm configuration variabledocumented in git-config[1].

Show what would be done, without making any changes.

Write the list of remote refs fetched in the FETCH_HEADfile directly under $GIT_DIR. This is the default.Passing --no-write-fetch-head from the command line tellsGit not to write the file. Under --dry-run option, thefile is never written.

When git fetch is used with <src>:<dst> refspec it mayrefuse to update the local branch as discussedin the <refspec> part below.This option overrides that check.

Keep downloaded pack.

Allow several <repository> and <group> arguments to bespecified. No <refspec>s may be specified.

Run git maintenance run --auto at the end to perform automaticrepository maintenance if needed. (--[no-]auto-gc is a synonym.)This is enabled by default.

Write a commit-graph after fetching. This overrides the configsetting fetch.writeCommitGraph.

Before fetching, remove any remote-tracking references that nolonger exist on the remote. Tags are not subject to pruningif they are fetched only because of the default tagauto-following or due to a --tags option. However, if tagsare fetched due to an explicit refspec (either on the commandline or in the remote configuration, for example if the remotewas cloned with the --mirror option), then they are alsosubject to pruning. Supplying --prune-tags is a shorthand forproviding the tag refspec.

See the PRUNING section below for more details.

Before fetching, remove any local tags that no longer exist onthe remote if --prune is enabled. This option should be usedmore carefully, unlike --prune it will remove any localreferences (local tags) that have been created. This option isa shorthand for providing the explicit tag refspec along with--prune, see the discussion about that in its documentation.

See the PRUNING section below for more details.

By default, tags that point at objects that are downloadedfrom the remote repository are fetched and stored locally.This option disables this automatic tag following. The defaultbehavior for a remote may be specified with the remote.<name>.tagOptsetting. See git-config[1].

When fetching refs listed on the command line, use thespecified refspec (can be given more than once) to map therefs to remote-tracking branches, instead of the values ofremote.*.fetch configuration variables for the remoterepository. Providing an empty <refspec> to the--refmap option causes Git to ignore the configuredrefspecs and rely entirely on the refspecs supplied ascommand-line arguments. See section on "Configured Remote-trackingBranches" for details.

Fetch all tags from the remote (i.e., fetch remote tagsrefs/tags/* into local tags with the same name), in additionto whatever else would otherwise be fetched. Using thisoption alone does not subject tags to pruning, even if --pruneis used (though tags may be pruned anyway if they are also thedestination of an explicit refspec; see --prune).

This option controls if and under what conditions new commits ofpopulated submodules should be fetched too. It can be used as aboolean option to completely disable recursion when set to no or tounconditionally recurse into all populated submodules when set toyes, which is the default when this option is used without anyvalue. Use on-demand to only recurse into a populated submodulewhen the superproject retrieves a commit that updates the submodule’sreference to a commit that isn’t already in the local submoduleclone. By default, on-demand is used, unlessfetch.recurseSubmodules is set (see git-config[1]).

Number of parallel children to be used for all forms of fetching.

If the --multiple option was specified, the different remotes will be fetchedin parallel. If multiple submodules are fetched, they will be fetched inparallel. To control them independently, use the config settingsfetch.parallel and submodule.fetchJobs (see git-config[1]).

Typically, parallel recursive and multi-remote fetches will be faster. Bydefault fetches are performed sequentially, not in parallel.

Disable recursive fetching of submodules (this has the same effect asusing the --recurse-submodules=no option).

If the remote is fetched successfully, add upstream(tracking) reference, used by argument-lessgit-pull[1] and other commands. For more information,see branch.<name>.merge and branch.<name>.remote ingit-config[1].

Prepend <path> to paths printed in informative messagessuch as "Fetching submodule foo". This option is usedinternally when recursing over submodules.

This option is used internally to temporarily provide anon-negative default value for the --recurse-submodulesoption. All other methods of configuring fetch’s submodulerecursion (such as settings in gitmodules[5] andgit-config[1]) override this option, as doesspecifying --[no-]recurse-submodules directly.

By default git fetch refuses to update the head whichcorresponds to the current branch. This flag disables thecheck. This is purely for the internal use for git pullto communicate with git fetch, and unless you areimplementing your own Porcelain you are not supposed touse it.

When given, and the repository to fetch from is handledby git fetch-pack, --exec=<upload-pack> is passed tothe command to specify non-default path for the commandrun on the other end.

Pass --quiet to git-fetch-pack and silence any other internallyused git commands. Progress is not reported to the standard errorstream.

Be verbose.

Progress status is reported on the standard error streamby default when it is attached to a terminal, unless -qis specified. This flag forces progress status even if thestandard error stream is not directed to a terminal.

Transmit the given string to the server when communicating usingprotocol version 2. The given string must not contain a NUL or LFcharacter. The server’s handling of server options, includingunknown ones, is server-specific.When multiple --server-option=<option> are given, they are allsent to the other side in the order listed on the command line.

By default, git checks if a branch is force-updated duringfetch. This can be disabled through fetch.showForcedUpdates, butthe --show-forced-updates option guarantees this check occurs.See git-config[1].

By default, git checks if a branch is force-updated duringfetch. Pass --no-show-forced-updates or set fetch.showForcedUpdatesto false to skip this check for performance reasons. If used duringgit-pull the --ff-only option will still check for forced updatesbefore attempting a fast-forward update. See git-config[1].

Use IPv4 addresses only, ignoring IPv6 addresses.

Use IPv6 addresses only, ignoring IPv4 addresses.

The "remote" repository that is the source of a fetchor pull operation. This parameter can be either a URL(see the section GIT URLS below) or the nameof a remote (see the section REMOTES below).

A name referring to a list of repositories as the valueof remotes.<group> in the configuration file.(See git-config[1]).

Specifies which refs to fetch and which local refs to update.When no <refspec>s appear on the command line, the refs to fetchare read from remote.<repository>.fetch variables instead(see CONFIGURED REMOTE-TRACKING BRANCHES below).

The format of a <refspec> parameter is an optional plus+, followed by the source <src>, followedby a colon :, followed by the destination ref <dst>.The colon can be omitted when <dst> is empty. <src> istypically a ref, but it can also be a fully spelled hex objectname.

A <refspec> may contain a * in its <src> to indicate a simple patternmatch. Such a refspec functions like a glob that matches any ref with thesame prefix. A pattern <refspec> must have a * in both the <src> and<dst>. It will map refs to the destination by replacing the * with thecontents matched from the source.

If a refspec is prefixed by ^, it will be interpreted as a negativerefspec. Rather than specifying which refs to fetch or which local refs toupdate, such a refspec will instead specify refs to exclude. A ref will beconsidered to match if it matches at least one positive refspec, and doesnot match any negative refspec. Negative refspecs can be useful to restrictthe scope of a pattern refspec so that it will not include specific refs.Negative refspecs can themselves be pattern refspecs. However, they may onlycontain a <src> and do not specify a <dst>. Fully spelled out hex objectnames are also not supported.

tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>;it requests fetching everything up to the given tag.

The remote ref that matches <src>is fetched, and if <dst> is not an empty string, an attemptis made to update the local ref that matches it.

Whether that update is allowed without --force depends on the refnamespace it’s being fetched to, the type of object being fetched, andwhether the update is considered to be a fast-forward. Generally, thesame rules apply for fetching as when pushing, see the <refspec>...section of git-push[1] for what those are. Exceptions to thoserules particular to git fetch are noted below.

Until Git version 2.20, and unlike when pushing withgit-push[1], any updates to refs/tags/* would be acceptedwithout + in the refspec (or --force). When fetching, we promiscuouslyconsidered all tag updates from a remote to be forced fetches. SinceGit version 2.20, fetching to update refs/tags/* works the same wayas when pushing. I.e. any updates will be rejected without + in therefspec (or --force).

Unlike when pushing with git-push[1], any updates outside ofrefs/{tags,heads}/* will be accepted without + in the refspec (or--force), whether that’s swapping e.g. a tree object for a blob, ora commit for another commit that’s doesn’t have the previous commit asan ancestor etc.

Unlike when pushing with git-push[1], there is noconfiguration which’ll amend these rules, and nothing like apre-fetch hook analogous to the pre-receive hook.

As with pushing with git-push[1], all of the rules describedabove about what’s not allowed as an update can be overridden byadding an the optional leading + to a refspec (or using --forcecommand line option). The only exception to this is that no amount offorcing will make the refs/heads/* namespace accept a non-commitobject.

Read refspecs, one per line, from stdin in addition to those providedas arguments. The "tag <name>" format is not supported.