Re: [PATCH v2 8/9] fetch doc: add a section on configured remote-tracking branches

[Marc Branchaud <mbranchaud@xiplink.com>]

On 14-06-03 06:16 PM, Junio C Hamano wrote:
> To resurrect a misleading mention removed in the previous step,
> add a section to explain how the remote-tracking configuration
> interacts with the refspecs given as the command-line arguments.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git-fetch.txt | 43 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 43 insertions(+)
> 
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> index 06106b9..d09736a 100644
> --- a/Documentation/git-fetch.txt
> +++ b/Documentation/git-fetch.txt
> @@ -51,6 +51,49 @@ include::pull-fetch-param.txt[]
>  include::urls-remotes.txt[]
>  
>  
> +CONFIGURED REMOTE-TRACKING BRANCHES
> +-----------------------------------
> +
> +You would often interact with the same remote repository by

s/would//

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

/variable/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` command is run without specifying what branches

s/command//

> +  and/or tags to fetch on the command line, e.g. `git fetch origin`
> +  or `git fetch`, the values configured to this variable are used as

s/values configured to this variable/`remote.<repository>.fetch` values/

> +  the refspecs to be used to fetch.  The example above will fetch

/to be used//

> +  all branches that exist on the `origin` (i.e. any ref that matches

s/on/in/

> +  the left-hand side of the value, `refs/heads/*`) and update the
> +  corresponding remote-tracking branches in `refs/remotes/origin/*`

s/in/in the/

> +  hierarchy.
> +
> +* When `git fetch` command is run with explicit branches and/or tags

s/command//

> +  to fetch on the command line, e.g. `git fetch origin master`, the
> +  <refspec> given on the command line (e.g. `master` in the example,
> +  which is a short-hand for `master:`, which in turn would mean
> +  "fetch the 'master' branch but I do not explicitly say what
> +  remote-tracking branch to update with it from the command line")
> +  determines what are to be fetched, and the example command will

Change "determines what are to be fetched" to "determines what gets fetched"
and move the phrase to before the parenthetical comment.

> +  fetch _only_ the 'master' branch.  The values of the variable are

s/values of the variable/`remote.<repository>.fetch` values/

> +  used to map the branch (i.e. `master`) to determine which

s/used to map the branch (i.e. `master`) to//

> +  remote-tracking branch, if any, is updated.  When used in this
> +  way, the values of the configuration variable do not have any

s/values of the configuration variable/`remote.<repository>.fetch` values/

		M.


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