git-fetch

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

ifndef::git-pull[] <group>:: A name referring to a list of repositories as the value of remotes.<group> in the configuration file. (See linkgit:git-config[1]). endif::git-pull[]

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

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

REMOTES ------------------

The name of one of the following can be used instead of 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 line because 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 previously configured using linkgit:git-remote[1], linkgit:git-config[1] or even by a manual edit to the $GIT_DIR/config file. The URL of this remote will be used to access the repository. The refspec of this remote will be used by default when you do not provide a refspec on the command line. The entry in the config file would appear like this:

	[remote "<name>"]
		url = <URL>
		pushurl = <pushurl>
		push = <refspec>
		fetch = <refspec>

The <pushurl> is used for pushes only. It is optional and defaults to <URL>. Pushing to a remote affects all defined pushurls or all defined urls if no pushurls are defined. Fetch, however, will only fetch from the first defined url if multiple urls are defined.

Named file in $GIT_DIR/remotes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

	URL: one of the above URL formats
	Push: <refspec>
	Pull: <refspec>

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

Named file in $GIT_DIR/branches ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

	<URL>#<head>

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

Depending on the operation, git will use one of the following refspecs, 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:

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

git push uses:

	HEAD:refs/heads/<head>

Branches in Git can optionally have an upstream remote branch. Git defaults to using the upstream branch for remote operations, for example:

• It’s the default for git pull or git fetch with no arguments.

• It’s the default for git push with no arguments, with some exceptions. For example, you can use the branch.<name>.pushRemote option to push to a different remote than you pull from, and by default with push.default=simple the upstream branch you configure must have the same name.

• Various commands, including git checkout and git status, will show you how many commits have been added to your current branch and the upstream since you forked from it, for example "Your branch and ’origin/main’ have diverged, and have 2 and 3 different commits each respectively".

The upstream is stored in .git/config, in the “remote” and “merge” fields. For example, if main’s upstream is origin/main:

[branch "main"]
   remote = origin
   merge = refs/heads/main

You can set an upstream branch explicitly with git push --set-upstream <remote> <branch> but Git will often automatically set the upstream for you, for example:

• When you clone a repository, Git will automatically set the upstream for the default branch.

• If you have the push.autoSetupRemote configuration option set, git push will automatically set the upstream the first time you push a branch.

• Checking out a remote-tracking branch with git checkout <branch> will automatically create a local branch with that name and set the upstream to the remote branch.

Upstream branches are sometimes referred to as "tracking information", as in "set the branch’s tracking information".

SECURITY -------- The fetch and push protocols are not designed to prevent one side from stealing data from the other repository that was not intended to be shared. If you have private data that you need to protect from a malicious peer, your best option is to store it in another repository. This applies to both clients and servers. In particular, namespaces on a server are not effective for read access control; you should only grant read access to a namespace to clients that you would trust with read access to the entire repository.

The known attack vectors are as follows:

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

1. As in #1, the attacker chooses an object ID X to steal. The victim sends an object Y that the attacker already has, and the attacker falsely claims 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.

Everything below this line in this section is selectively included from the linkgit:git-config[1] documentation. The content is the same as what’s found there:

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

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 transfer.fsckObjects is used instead.

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
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
If the number of objects fetched over the Git native transfer is below this limit, then the objects will be unpacked into loose object files. However if the number of received objects equals or exceeds this limit then the received pack will be stored as a pack, after adding any missing delta bases. Storing the pack from a push can make the push operation complete faster, especially on slow filesystems. If not set, the value of transfer.unpackLimit is used instead.

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

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
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 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 certainly result in a larger-than-necessary packfile, but will skip 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 error out.

See also the --negotiate-only and --negotiation-restrict options to linkgit:git-fetch[1].

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.

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

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

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 linkgit:git-clone[1]. git clone --bundle-uri will set the fetch.bundleURI value if the supplied bundle URI contains a bundle list that is organized for incremental fetches.

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
When using fetch.bundleURI to fetch incrementally from a bundle 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 value.

The creation token values are chosen by the provider serving the specific bundle URI. If you modify the URI at fetch.bundleURI, then be sure to remove the value for the fetch.bundleCreationToken value before fetching.

fetch.followRemoteHEAD
When fetching using a default refspec, this setting determines how to handle differences between a fetched remote’s HEAD and the local remotes/<name>/HEAD symbolic-ref. Its value is one of