| git-fetch(1) |
| ============ |
| |
| NAME |
| ---- |
| git-fetch - Download objects and refs from another repository |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git fetch' [<options>] [<repository> [<refspec>...]] |
| 'git fetch' [<options>] <group> |
| 'git fetch' --multiple [<options>] [(<repository> | <group>)...] |
| 'git fetch' --all [<options>] |
| |
| |
| DESCRIPTION |
| ----------- |
| 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 <refspec> below for ways to control this behavior). |
| |
| 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.<name>.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. |
| |
| 'git fetch' can fetch from either a single named repository or URL, |
| or from several repositories at once if <group> is given and |
| there is a remotes.<group> entry in the configuration file. |
| (See linkgit: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 names |
| they point at, are written to `.git/FETCH_HEAD`. This information |
| may be used by scripts or other git commands, such as linkgit:git-pull[1]. |
| |
| OPTIONS |
| ------- |
| include::fetch-options.txt[] |
| |
| include::pull-fetch-param.txt[] |
| |
| include::urls-remotes.txt[] |
| |
| |
| CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] |
| ------------------------------------------- |
| |
| You often interact with the same remote repository by |
| regularly and repeatedly fetching from it. In order to keep track |
| of the progress of such a remote repository, `git fetch` allows you |
| to configure `remote.<repository>.fetch` configuration variables. |
| |
| Typically such a variable may look like this: |
| |
| ------------------------------------------------ |
| [remote "origin"] |
| fetch = +refs/heads/*:refs/remotes/origin/* |
| ------------------------------------------------ |
| |
| This configuration is used in two ways: |
| |
| * When `git fetch` is run without specifying what branches |
| and/or tags to fetch on the command line, e.g. `git fetch origin` |
| or `git fetch`, `remote.<repository>.fetch` values are used as |
| the refspecs--they specify which refs to fetch and which local refs |
| to update. The example above will fetch |
| all branches that exist in the `origin` (i.e. any ref that matches |
| the left-hand side of the value, `refs/heads/*`) and update the |
| corresponding remote-tracking branches in the `refs/remotes/origin/*` |
| hierarchy. |
| |
| * When `git fetch` is run with explicit branches and/or tags |
| to fetch on the command line, e.g. `git fetch origin master`, the |
| <refspec>s given on the command line determine what are to be |
| fetched (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 what |
| remote-tracking branch to update with it from the command line"), |
| and the example command will |
| fetch _only_ the 'master' branch. The `remote.<repository>.fetch` |
| values determine which |
| remote-tracking branch, if any, is updated. When used in this |
| way, the `remote.<repository>.fetch` values do not have any |
| effect in deciding _what_ gets fetched (i.e. the values are not |
| used as refspecs when the command-line lists refspecs); they are |
| only used to decide _where_ the refs that are fetched are stored |
| by acting as a mapping. |
| |
| The latter use of the `remote.<repository>.fetch` values can be |
| overridden by giving the `--refmap=<refspec>` parameter(s) on the |
| command line. |
| |
| OUTPUT |
| ------ |
| |
| The output of "git fetch" depends on the transport method used; this |
| section 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 line |
| representing the status of a single ref. Each line is of the form: |
| |
| ------------------------------- |
| <flag> <summary> <from> -> <to> [<reason>] |
| ------------------------------- |
| |
| The status of up-to-date refs is shown only if the --verbose option is |
| used. |
| |
| In compact output mode, specified with configuration variable |
| fetch.output, if either entire `<from>` or `<to>` is found in the |
| other string, it will be substituted with `*` in the other string. For |
| example, `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 new |
| values of the ref in a form suitable for using as an argument to |
| `git 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 its |
| `refs/<type>/` prefix. In the case of deletion, the name of |
| the remote ref is "(none)". |
| |
| to:: |
| The name of the local ref being updated, minus its |
| `refs/<type>/` prefix. |
| |
| reason:: |
| A human-readable explanation. In the case of successfully fetched |
| refs, no explanation is needed. For a failed ref, the reason for |
| failure is described. |
| |
| EXAMPLES |
| -------- |
| |
| * Update the remote-tracking branches: |
| + |
| ------------------------------------------------ |
| $ 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.<name>.fetch option is used to specify a non-default |
| refspec. |
| |
| * Using refspecs explicitly: |
| + |
| ------------------------------------------------ |
| $ git fetch origin +pu:pu maint:tmp |
| ------------------------------------------------ |
| + |
| This updates (or creates, as necessary) branches `pu` and `tmp` in |
| the local repository by fetching from the branches (respectively) |
| `pu` and `maint` from the remote repository. |
| + |
| The `pu` branch will be updated even if it is 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 local |
| repository: |
| + |
| ------------------------------------------------ |
| $ git fetch git://git.kernel.org/pub/scm/git/git.git maint |
| $ git log FETCH_HEAD |
| ------------------------------------------------ |
| + |
| The first command fetches the `maint` branch from the repository at |
| `git://git.kernel.org/pub/scm/git/git.git` and the second command uses |
| `FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched |
| objects will eventually be removed by git's built-in housekeeping (see |
| linkgit:git-gc[1]). |
| |
| include::transfer-data-leaks.txt[] |
| |
| BUGS |
| ---- |
| Using --recurse-submodules can only fetch new commits in already checked |
| out submodules right now. When e.g. upstream added a new submodule in the |
| just fetched commits of the superproject the submodule itself can not be |
| fetched, making it impossible to check out that submodule later without |
| having to do a fetch again. This is expected to be fixed in a future Git |
| version. |
| |
| SEE ALSO |
| -------- |
| linkgit:git-pull[1] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |