diff options
| author | Junio C Hamano <gitster@pobox.com> | 2014-06-20 13:14:10 -0700 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2014-06-20 13:14:10 -0700 |
| commit | a668853c6715b481bff347d7a08f5d885fc95f86 (patch) | |
| tree | 0c3dd44c39d7ef3f55896e93b2a7a1100579f77a /Documentation | |
| parent | 9fe49ae7d7750297680442bcee8cd13959303247 (diff) | |
| parent | db4e4113ea33ece52c5988f9b9f7c0559c802602 (diff) | |
| download | git-a668853c6715b481bff347d7a08f5d885fc95f86.tar.gz | |
Merge branch 'jc/fetch-pull-refmap'
* jc/fetch-pull-refmap:
docs: Explain the purpose of fetch's and pull's <refspec> parameter.
fetch: allow explicit --refmap to override configuration
fetch doc: add a section on configured remote-tracking branches
fetch doc: remove "short-cut" section
fetch doc: update refspec format description
fetch doc: on pulling multiple refspecs
fetch doc: remove notes on outdated "mixed layout"
fetch doc: update note on '+' in front of the refspec
fetch doc: move FETCH_HEAD material lower and add an example
fetch doc: update introductory part for clarity
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/fetch-options.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-fetch.txt | 90 | ||||
| -rw-r--r-- | Documentation/pull-fetch-param.txt | 81 |
3 files changed, 122 insertions, 57 deletions
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 92c68c3fda..b09a783ee3 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -72,6 +72,14 @@ endif::git-pull[] setting. See linkgit:git-config[1]. ifndef::git-pull[] +--refmap=<refspec>:: + When fetching refs listed on the command line, use the + specified refspec (can be given more than once) to map the + refs to remote-tracking branches, instead of the values of + `remote.*.fetch` configuration variables for the remote + repository. See section on "Configured Remote-tracking + Branches" for details. + -t:: --tags:: Fetch all tags from the remote (i.e., fetch remote tags diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 5809aa4eb9..8deb61469d 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,55 @@ 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. + + EXAMPLES -------- @@ -76,6 +127,19 @@ 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]). BUGS ---- diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 18cffc25b8..1ebbf1d738 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -12,9 +12,23 @@ ifndef::git-pull[] endif::git-pull[] <refspec>:: - The format of a <refspec> parameter is an optional plus - `+`, followed by the source ref <src>, followed - by a colon `:`, followed by the destination ref <dst>. + Specifies which refs to fetch and which local refs to update. + When no <refspec>s appear on the command line, the refs to fetch + are read from `remote.<repository>.fetch` variables instead +ifndef::git-pull[] + (see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below). +endif::git-pull[] +ifdef::git-pull[] + (see linkgit:git-fetch[1]). +endif::git-pull[] ++ +The format of a <refspec> parameter is an optional plus +`+`, followed by the source ref <src>, followed +by a colon `:`, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty. ++ +`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 empty string, the local @@ -24,55 +38,34 @@ is updated even if it does not result in a fast-forward update. + [NOTE] -If the remote branch from which you want to pull is -modified in non-linear ways such as being rewound and -rebased frequently, then a pull will attempt a merge with -an older version of itself, likely conflict, and fail. -It is under these conditions that you would want to use -the `+` sign to indicate non-fast-forward updates will -be needed. There is currently no easy way to determine -or declare that a branch will be made available in a -repository with this behavior; the pulling user simply +When the remote branch you want to fetch is known to +be rewound and rebased regularly, it is expected that +its new tip will not be descendant of its previous tip +(as stored in your remote-tracking branch the last time +you fetched). You would want +to use the `+` sign to indicate non-fast-forward updates +will be needed for such branches. There is no way to +determine or declare that a branch will be made available +in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch. -+ -[NOTE] -You never do your own development on branches that appear -on the right hand side of a <refspec> colon on `Pull:` lines; -they are to be updated by 'git fetch'. If you intend to do -development derived from a remote branch `B`, have a `Pull:` -line to track it (i.e. `Pull: B:remote-B`), and have a separate -branch `my-B` to do your development on top of it. The latter -is created by `git branch my-B remote-B` (or its equivalent `git -checkout -b my-B remote-B`). Run `git fetch` to keep track of -the progress of the remote side, and when you see something new -on the remote branch, merge it into your development branch with -`git pull . remote-B`, while you are on `my-B` branch. +ifdef::git-pull[] + [NOTE] There is a difference between listing multiple <refspec> directly on 'git pull' command line and having multiple -`Pull:` <refspec> lines for a <repository> and running +`remote.<repository>.fetch` entries in your configuration +for a <repository> and running a 'git pull' command without any explicit <refspec> parameters. -<refspec> listed explicitly on the command line are always +<refspec>s listed explicitly on the command line are always merged into the current branch after fetching. In other words, -if you list more than one remote refs, you would be making -an Octopus. While 'git pull' run without any explicit <refspec> -parameter takes default <refspec>s from `Pull:` lines, it -merges only the first <refspec> found into the current branch, -after fetching all the remote refs. This is because making an +if you list more than one remote ref, 'git pull' will create +an Octopus merge. On the other hand, if you do not list any +explicit <refspec> parameter on the command line, 'git pull' +will fetch all the <refspec>s it finds in the +`remote.<repository>.fetch` configuration and merge +only the first <refspec> found into the current branch. +This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one-go by fetching more than one is often useful. -+ -Some short-cut notations are also supported. -+ -* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; - it requests fetching everything up to the given tag. -ifndef::git-pull[] -* A parameter <ref> without a colon fetches that ref into FETCH_HEAD, -endif::git-pull[] -ifdef::git-pull[] -* A parameter <ref> without a colon merges <ref> into the current - branch, endif::git-pull[] - and updates the remote-tracking branches (if any). |