diff options
Diffstat (limited to 'Documentation/git-fetch.txt')
| -rw-r--r-- | Documentation/git-fetch.txt | 143 |
1 files changed, 130 insertions, 13 deletions
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 5809aa4eb9..b153aefa68 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -17,22 +17,20 @@ SYNOPSIS DESCRIPTION ----------- -Fetches named heads or tags from one or more other repositories, -along with the objects necessary to complete them. +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). -The ref names and their object names of fetched refs are stored -in `.git/FETCH_HEAD`. This information is left for a later merge -operation done by 'git merge'. - -By default, tags are auto-followed. This means that when fetching -from a remote, any tags on the remote that point to objects that exist -in the local repository are fetched. The effect is to fetch tags that +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, by -configuring remote.<name>.tagopt, or by using a refspec that fetches -tags explicitly. +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, +'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]). @@ -40,6 +38,10 @@ there is a remotes.<group> entry in the configuration file. 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[] @@ -49,6 +51,106 @@ 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 -------- @@ -76,6 +178,21 @@ the local repository by fetching from the branches (respectively) 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 ---- |