NAME

git-fetch - Download objects and refs from another repository

SYNOPSIS

  1. git fetch [<options>] [<repository> [<refspec>…​]]
  2. git fetch [<options>] <group>
  3. git fetch --multiple [<options>] [(<repository> | <group>)…​]
  4. git fetch --all [<options>]

DESCRIPTION

Fetch branches and/or tags (collectively, "refs") from one or moreother repositories, along with the objects necessary to complete theirhistories. Remote-tracking branches are updated (see the descriptionof <refspec> below for ways to control this behavior).

By default, any tag that points into the histories being fetched isalso fetched; the effect is to fetch tags thatpoint at branches that you are interested in. This default behaviorcan be changed by using the —tags or —no-tags options or byconfiguring remote.<name>.tagOpt. By using a refspec that fetches tagsexplicitly, you can fetch tags that do not point into branches youare interested in as well.

git fetch can fetch from either a single named repository or URL,or from several repositories at once if <group> is given andthere is a remotes.<group> entry in the configuration file.(See git-config[1]).

When no remote is specified, by default the origin remote will be used,unless there’s an upstream branch configured for the current branch.

The names of refs that are fetched, together with the object namesthey point at, are written to .git/FETCH_HEAD. This informationmay be used by scripts or other git commands, such as git-pull[1].

OPTIONS

  • —all

  • Fetch all remotes.

  • -a

  • —append

  • 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.

  • —depth=

  • 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.

  • —deepen=

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

  • —shallow-since=

  • Deepen or shorten the history of a shallow repository toinclude all reachable commits after .

  • —shallow-exclude=

  • 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.

  • —unshallow

  • 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.

  • —update-shallow

  • 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.

  • —negotiation-tip=

  • 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].

  • —dry-run

  • Show what would be done, without making any changes.

  • -f

  • —force

  • 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.

  • -k

  • —keep

  • Keep downloaded pack.

  • —multiple

  • Allow several and arguments to bespecified. No s may be specified.

  • —[no-]auto-gc

  • Run git gc —auto at the end to perform garbage collectionif needed. This is enabled by default.

  • -p

  • —prune
  • 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.

  • -P
  • —prune-tags
  • 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.

  • -n
  • —no-tags

  • 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..tagOptsetting. See git-config[1].

  • —refmap=

  • 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. See section on "Configured Remote-trackingBranches" for details.

  • -t

  • —tags

  • 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).

  • —recurse-submodules[=yes|on-demand|no]

  • 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.

  • -j

  • —jobs=

  • Number of parallel children to be used for fetching submodules.Each will fetch from different submodules, such that fetching manysubmodules will be faster. By default submodules will be fetchedone at a time.

  • —no-recurse-submodules

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

  • —submodule-prefix=

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

  • —recurse-submodules-default=[yes|on-demand]

  • 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.

  • -u

  • —update-head-ok

  • 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 pull_to communicate with _git fetch, and unless you areimplementing your own Porcelain you are not supposed touse it.

  • —upload-pack

  • 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.

  • -q

  • —quiet

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

  • -v

  • —verbose

  • Be verbose.

  • —progress

  • 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.

  • -o

  • —server-option=

  • 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.

  • —show-forced-updates

  • 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].

  • —no-show-forced-updates

  • 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].

  • -4

  • —ipv4

  • Use IPv4 addresses only, ignoring IPv6 addresses.

  • -6

  • —ipv6

  • 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. in the configuration file.(See git-config[1]).

  • Specifies which refs to fetch and which local refs to update.When no 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 parameter is an optional plus+, followed by the source , followedby a colon :, followed by the destination ref .The colon can be omitted when is empty. istypically a ref, but it can also be a fully spelled hex objectname.

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 is fetched, and if 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.

NoteWhen the remote branch you want to fetch is known tobe rewound and rebased regularly, it is expected thatits new tip will not be descendant of its previous tip(as stored in your remote-tracking branch the last timeyou fetched). You would wantto use the + sign to indicate non-fast-forward updateswill be needed for such branches. There is no way todetermine or declare that a branch will be made availablein a repository with this behavior; the pulling user simplymust know this is the expected usage pattern for a branch.

GIT URLS

In general, URLs contain information about the transport protocol, theaddress of the remote server, and the path to the repository.Depending on the transport protocol, some of this information may beabsent.

Git supports ssh, git, http, and https protocols (in addition, ftp,and ftps can be used for fetching, but this is inefficient anddeprecated; do not use it).

The native transport (i.e. git:// URL) does no authentication andshould be used with caution on unsecured networks.

The following syntaxes may be used with them:

  • ssh://[user@]host.xz[:port]/path/to/repo.git/

  • git://host.xz[:port]/path/to/repo.git/

  • http[s]://host.xz[:port]/path/to/repo.git/

  • ftp[s]://host.xz[:port]/path/to/repo.git/

An alternative scp-like syntax may also be used with the ssh protocol:

  • [user@]host.xz:path/to/repo.git/

This syntax is only recognized if there are no slashes before thefirst colon. This helps differentiate a local path that contains acolon. For example the local path foo:bar could be specified as anabsolute path or ./foo:bar to avoid being misinterpreted as an sshurl.

The ssh and git protocols additionally support ~username expansion:

  • ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/

  • git://host.xz[:port]/~[user]/path/to/repo.git/

  • [user@]host.xz:/~[user]/path/to/repo.git/

For local repositories, also supported by Git natively, the followingsyntaxes may be used:

  • /path/to/repo.git/

  • file:///path/to/repo.git/

These two syntaxes are mostly equivalent, except when cloning, whenthe former implies —local option. See git-clone[1] fordetails.

When Git doesn’t know how to handle a certain transport protocol, itattempts to use the remote-<transport> remote helper, if oneexists. To explicitly request a remote helper, the following syntaxmay be used:

  • ::

where <address> may be a path, a server and path, or an arbitraryURL-like string recognized by the specific remote helper beinginvoked. See gitremote-helpers[7] for details.

If there are a large number of similarly-named remote repositories andyou want to use a different format for them (such that the URLs youuse will be rewritten into URLs that work), you can create aconfiguration section of the form:

  1.     [url "<actual url base>"]
  2.         insteadOf = <other url base>

For example, with this:

  1.     [url "git://git.host.xz/"]
  2.         insteadOf = host.xz:/path/to/
  3.         insteadOf = work:

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will berewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

If you want to rewrite URLs for push only, you can create aconfiguration section of the form:

  1.     [url "<actual url base>"]
  2.         pushInsteadOf = <other url base>

For example, with this:

  1.     [url "ssh://example.org/"]
  2.         pushInsteadOf = git://example.org/

a URL like "git://example.org/path/to/repo.git" will be rewritten to"ssh://example.org/path/to/repo.git" for pushes, but pulls will stilluse the original URL.

REMOTES

The name of one of the following can be used insteadof a URL as <repository> argument:

  • a remote in the Git configuration file: $GIT_DIR/config,

  • a file in the $GIT_DIR/remotes directory, or

  • a file in the $GIT_DIR/branches directory.

All of these also allow you to omit the refspec from the command linebecause they each contain a refspec which git will use by default.

Named remote in configuration file

You can choose to provide the name of a remote which you had previouslyconfigured using git-remote[1], git-config[1]or even by a manual edit to the $GIT_DIR/config file. The URL ofthis remote will be used to access the repository. The refspecof this remote will be used by default when you donot provide a refspec on the command line. The entry in theconfig file would appear like this:

  1.     [remote "<name>"]
  2.         url = <url>
  3.         pushurl = <pushurl>
  4.         push = <refspec>
  5.         fetch = <refspec>

The <pushurl> is used for pushes only. It is optional and defaultsto <url>.

Named file in $GIT_DIR/remotes

You can choose to provide the name of afile in $GIT_DIR/remotes. The URLin this file will be used to access the repository. The refspecin this file will be used as default when you do notprovide a refspec on the command line. This file should have thefollowing format:

  1.     URL: one of the above URL format
  2.     Push: <refspec>
  3.     Pull: <refspec>

Push: lines are used by git push andPull: lines are used by git pull and git fetch.Multiple Push: and Pull: lines maybe specified for additional branch mappings.

Named file in $GIT_DIR/branches

You can choose to provide the name of afile in $GIT_DIR/branches.The URL in this file will be used to access the repository.This file should have the following format:

  1.     <url>#<head>

<url> is required; #<head> is optional.

Depending on the operation, git will use one of the followingrefspecs, if you don’t provide one on the command line.<branch> is the name of this file in $GIT_DIR/branches and<head> defaults to master.

git fetch uses:

  1.     refs/heads/<head>:refs/heads/<branch>

git push uses:

  1.     HEAD:refs/heads/<head>

CONFIGURED REMOTE-TRACKING BRANCHES

You often interact with the same remote repository byregularly and repeatedly fetching from it. In order to keep trackof the progress of such a remote repository, git fetch allows youto configure remote.<repository>.fetch configuration variables.

Typically such a variable may look like this:

  1. [remote "origin"]
  2.     fetch = +refs/heads/*:refs/remotes/origin/*

This configuration is used in two ways:

  • When git fetch is run without specifying what branchesand/or tags to fetch on the command line, e.g. git fetch originor git fetch, remote.<repository>.fetch values are used asthe refspecs—​they specify which refs to fetch and which local refsto update. The example above will fetchall branches that exist in the origin (i.e. any ref that matchesthe left-hand side of the value, refs/heads/) and update thecorresponding remote-tracking branches in the refs/remotes/origin/hierarchy.

  • When git fetch is run with explicit branches and/or tagsto fetch on the command line, e.g. git fetch origin master, thes given on the command line determine what are to befetched (e.g. master in the example,which is a short-hand for master:, which in turn means"fetch the master branch but I do not explicitly say whatremote-tracking branch to update with it from the command line"),and the example command willfetch only the master branch. The remote.<repository>.fetchvalues determine whichremote-tracking branch, if any, is updated. When used in thisway, the remote.<repository>.fetch values do not have anyeffect in deciding what gets fetched (i.e. the values are notused as refspecs when the command-line lists refspecs); they areonly used to decide where the refs that are fetched are storedby acting as a mapping.

The latter use of the remote.<repository>.fetch values can beoverridden by giving the —refmap=<refspec> parameter(s) on thecommand line.

PRUNING

Git has a default disposition of keeping data unless it’s explicitlythrown away; this extends to holding onto local references to brancheson remotes that have themselves deleted those branches.

If left to accumulate, these stale references might make performanceworse on big and busy repos that have a lot of branch churn, ande.g. make the output of commands like git branch -a —contains<commit> needlessly verbose, as well as impacting anything elsethat’ll work with the complete set of known references.

These remote-tracking references can be deleted as a one-off witheither of:

  1. # While fetching
  2. $ git fetch --prune <name>
  3.  
  4. # Only prune, don't fetch
  5. $ git remote prune <name>

To prune references as part of your normal workflow without needing toremember to run that, set fetch.prune globally, orremote.<name>.prune per-remote in the config. Seegit-config[1].

Here’s where things get tricky and more specific. The pruning featuredoesn’t actually care about branches, instead it’ll prune local <→remote-references as a function of the refspec of the remote (see<refspec> and CONFIGURED REMOTE-TRACKING BRANCHES above).

Therefore if the refspec for the remote includese.g. refs/tags/:refs/tags/, or you manually run e.g. git fetch—prune <name> "refs/tags/:refs/tags/" it won’t be stale remotetracking branches that are deleted, but any local tag that doesn’texist on the remote.

This might not be what you expect, i.e. you want to prune remote<name>, but also explicitly fetch tags from it, so when you fetchfrom it you delete all your local tags, most of which may not havecome from the <name> remote in the first place.

So be careful when using this with a refspec likerefs/tags/:refs/tags/, or any other refspec which might mapreferences from multiple remotes to the same local namespace.

Since keeping up-to-date with both branches and tags on the remote isa common use-case the —prune-tags option can be supplied along with—prune to prune local tags that don’t exist on the remote, andforce-update those tags that differ. Tag pruning can also be enabledwith fetch.pruneTags or remote.<name>.pruneTags in the config. Seegit-config[1].

The —prune-tags option is equivalent to havingrefs/tags/:refs/tags/ declared in the refspecs of the remote. Thiscan lead to some seemingly strange interactions:

  1. # These both fetch tags
  2. $ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'
  3. $ git fetch --no-tags --prune-tags origin

The reason it doesn’t error out when provided without —prune or itsconfig versions is for flexibility of the configured versions, and tomaintain a 1=1 mapping between what the command line flags do, andwhat the configuration versions do.

It’s reasonable to e.g. configure fetch.pruneTags=true in~/.gitconfig to have tags pruned whenever git fetch —prune isrun, without making every invocation of git fetch without —prunean error.

Pruning tags with —prune-tags also works when fetching a URLinstead of a named remote. These will all prune tags not found onorigin:

  1. $ git fetch origin --prune --prune-tags
  2. $ git fetch origin --prune 'refs/tags/*:refs/tags/*'
  3. $ git fetch <url of origin> --prune --prune-tags
  4. $ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*'

OUTPUT

The output of "git fetch" depends on the transport method used; thissection describes the output when fetching over the Git protocol(either locally or via ssh) and Smart HTTP protocol.

The status of the fetch is output in tabular form, with each linerepresenting the status of a single ref. Each line is of the form:

  1.  <flag> <summary> <from> -> <to> [<reason>]

The status of up-to-date refs is shown only if the —verbose option isused.

In compact output mode, specified with configuration variablefetch.output, if either entire <from> or <to> is found in theother string, it will be substituted with in the other string. Forexample, master -> origin/master becomes master -> origin/.

  • flag
  • A single character indicating the status of the ref:
  • (space)

  • for a successfully fetched fast-forward;

  • +

  • for a successful forced update;

  • -

  • for a successfully pruned ref;

  • t

  • for a successful tag update;

  • *

  • for a successfully fetched new ref;

  • !

  • for a ref that was rejected or failed to update; and

  • =

  • for a ref that was up to date and did not need fetching.
  • summary

  • For a successfully fetched ref, the summary shows the old and newvalues of the ref in a form suitable for using as an argument togit log (this is <old>..<new> in most cases, and<old>…<new> for forced non-fast-forward updates).

  • from

  • The name of the remote ref being fetched from, minus itsrefs/<type>/ prefix. In the case of deletion, the name ofthe remote ref is "(none)".

  • to

  • The name of the local ref being updated, minus itsrefs/<type>/ prefix.

  • reason

  • A human-readable explanation. In the case of successfully fetchedrefs, no explanation is needed. For a failed ref, the reason forfailure is described.

EXAMPLES

  • Update the remote-tracking branches:
  1. $ git fetch origin

The above command copies all branches from the remote refs/heads/namespace and stores them to the local refs/remotes/origin/ namespace,unless the branch..fetch option is used to specify a non-defaultrefspec.

  • Using refspecs explicitly:
  1. $ git fetch origin +pu:pu maint:tmp

This updates (or creates, as necessary) branches pu and tmp inthe local repository by fetching from the branches (respectively)pu and maint from the remote repository.

The pu branch will be updated even if it does not fast-forward,because it is prefixed with a plus sign; tmp will not be.

  • Peek at a remote’s branch, without configuring the remote in your localrepository:
  1. $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
  2. $ git log FETCH_HEAD

The first command fetches the maint branch from the repository atgit://git.kernel.org/pub/scm/git/git.git and the second command usesFETCH_HEAD to examine the branch with git-log[1]. The fetchedobjects will eventually be removed by git’s built-in housekeeping (seegit-gc[1]).

SECURITY

The fetch and push protocols are not designed to prevent one side fromstealing data from the other repository that was not intended to beshared. If you have private data that you need to protect from a maliciouspeer, your best option is to store it in another repository. This appliesto both clients and servers. In particular, namespaces on a server are noteffective for read access control; you should only grant read access to anamespace to clients that you would trust with read access to the entirerepository.

The known attack vectors are as follows:

  • The victim sends "have" lines advertising the IDs of objects it has thatare not explicitly intended to be shared but can be used to optimize thetransfer if the peer also has them. The attacker chooses an object ID Xto steal and sends a ref to X, but isn’t required to send the content ofX because the victim already has it. Now the victim believes that theattacker has X, and it sends the content of X back to the attackerlater. (This attack is most straightforward for a client to perform on aserver, by creating a ref to X in the namespace the client has accessto and then fetching it. The most likely way for a server to perform iton a client is to "merge" X into a public branch and hope that the userdoes additional work on this branch and pushes it back to the serverwithout noticing the merge.)

  • As in #1, the attacker chooses an object ID X to steal. The victim sendsan object Y that the attacker already has, and the attacker falselyclaims to have X and not Y, so the victim sends Y as a delta against X.The delta reveals regions of X that are similar to Y to the attacker.

BUGS

Using —recurse-submodules can only fetch new commits in already checkedout submodules right now. When e.g. upstream added a new submodule in thejust fetched commits of the superproject the submodule itself cannot befetched, making it impossible to check out that submodule later withouthaving to do a fetch again. This is expected to be fixed in a future Gitversion.

SEE ALSO

git-pull[1]

GIT

Part of the git[1] suite