[PATCH 0/5] Documentation updates for 'git fetch'

[PATCH 0/5] Documentation updates for 'git fetch'

[Junio C Hamano]

Noticed that this page has antiquated description, which may still
be correct, that can use some modernization.

There are a few more larger updates coming, but these are small
enough to be reviewed separately and quickly, so I am sending them
out early.

Junio C Hamano (5):
  fetch doc: update introductory part for clarity
  fetch doc: update note on '+' in front of the refspec
  fetch doc: remove notes on outdated "mixed layout"
  fetch doc: on pulling multiple refspecs
  fetch doc: update refspec format description

 Documentation/git-fetch.txt        | 29 ++++++++++++++-----------
 Documentation/pull-fetch-param.txt | 44 ++++++++++++++++----------------------
 2 files changed, 34 insertions(+), 39 deletions(-)

-- 
2.0.0-479-g59ac8f9

[PATCH 1/5] fetch doc: update introductory part for clarity

[Junio C Hamano]

 - "Branches" is a more common way to say "heads" in these days.

 - Remote-tracking branches are used a lot more these days and it is
   worth mentioning that it is one of the primary side effects of
   the command to update them.

 - Avoid "X. That means Y."  If Y is easier to understand to
   readers, just say that upfront.

 - Use of explicit refspec to fetch tags does not have much to do
   with turning "auto following" on or off.  It is a way to fetch
   tags that otherwise would not be fetched by auto-following.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-fetch.txt | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 5809aa4..d5f5b54 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -17,20 +17,23 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Fetches named heads or tags from one or more other repositories,
-along with the objects necessary to complete them.
-
-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
+Fetch branches and/or tags (collectively, "refs") from one or more
+other repositories, along with the objects necessary to complete the
+histories of them.
+
+The names of refs that are fetched, together with the object names
+they point at, are written to `.git/FETCH_HEAD`.  This information
+is used by a later merge operation done by 'git merge'.  In addition,
+the remote-tracking branches may be updated (see description on
+<refspec> below for details).
+
+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,
 or from several repositories at once if <group> is given and
-- 
2.0.0-479-g59ac8f9

[PATCH 2/5] fetch doc: update note on '+' in front of the refspec

[Junio C Hamano]

While it is not *wrong* per-se to say that pulling a rewound/rebased
branch will lead to an unnecessary merge conflict, that is not what
the leading "+" sign to allow non-fast-forward update of remote-tracking
branch is at all.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pull-fetch-param.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 18cffc2..2a7e2b7 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -24,15 +24,15 @@ 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
+the tip of it will not be descendant of the commit that
+used to be at its tip the last time you fetched it and
+stored in your remote-tracking branch.  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]
-- 
2.0.0-479-g59ac8f9

[PATCH 3/5] fetch doc: remove notes on outdated "mixed layout"

[Junio C Hamano]

In old days before Git 1.5, it was customery for "git fetch" to use
the same local branch namespace to keep track of the remote-tracking
branches, and it was necessary to tell users not to check them out
and commit on them.  Since everybody uses the separate remote layout
these days, there is no need to warn against the practice to check
out the right-hand side of <refspec> and build on it---the RHS is
typically not even a local branch.

Incidentally, this also kills one mention of "Pull:" line of
$GIT_DIR/remotes/* configuration, which is a lot less familiar to
new people than the more modern remote.*.fetch configuration
variable.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pull-fetch-param.txt | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 2a7e2b7..e266c2d 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -36,19 +36,6 @@ 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.
-+
-[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
-- 
2.0.0-479-g59ac8f9

[PATCH 4/5] fetch doc: on pulling multiple refspecs

[Junio C Hamano]

Replace desription of old-style "Pull:" lines in remotes/
configuration with modern remote.*.fetch variables.

As this note applies only to "git pull", enable it only
in git-pull manual page.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pull-fetch-param.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index e266c2d..ea4c5a6 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -34,22 +34,26 @@ 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.
+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
 'git pull' command without any explicit <refspec> parameters.
 <refspec> 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
+an Octopus merge. On the other hand, 'git pull' that is run
+without any explicit <refspec> parameter takes default
+<refspec>s from `remote.<repository>.fetch` configuration, it
 merges only the first <refspec> found into the current branch,
-after fetching all the remote refs.  This is because making an
+after fetching all the remote refs specified.  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.
+endif::git-pull[]
 +
 Some short-cut notations are also supported.
 +
-- 
2.0.0-479-g59ac8f9

[PATCH 5/5] fetch doc: update refspec format description

[Junio C Hamano]

The text made it sound as if the leading plus is the only thing that
is optional, and forgot that <lhs> is the same as <lhs>:, i.e. fetch
it and do not store anywhere.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pull-fetch-param.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index ea4c5a6..27cfd5c 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -15,6 +15,7 @@ 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.
 +
 The remote ref that matches <src>
 is fetched, and if <dst> is not empty string, the local
-- 
2.0.0-479-g59ac8f9

Re: [PATCH 1/5] fetch doc: update introductory part for clarity

[Marc Branchaud]

On 14-05-29 06:42 PM, Junio C Hamano wrote:
>  - "Branches" is a more common way to say "heads" in these days.
> 
>  - Remote-tracking branches are used a lot more these days and it is
>    worth mentioning that it is one of the primary side effects of
>    the command to update them.
> 
>  - Avoid "X. That means Y."  If Y is easier to understand to
>    readers, just say that upfront.
> 
>  - Use of explicit refspec to fetch tags does not have much to do
>    with turning "auto following" on or off.  It is a way to fetch
>    tags that otherwise would not be fetched by auto-following.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git-fetch.txt | 29 ++++++++++++++++-------------
>  1 file changed, 16 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> index 5809aa4..d5f5b54 100644
> --- a/Documentation/git-fetch.txt
> +++ b/Documentation/git-fetch.txt
> @@ -17,20 +17,23 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Fetches named heads or tags from one or more other repositories,
> -along with the objects necessary to complete them.
> -
> -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
> +Fetch branches and/or tags (collectively, "refs") from one or more
> +other repositories, along with the objects necessary to complete the
> +histories of them.

Phrasing: s/the histories of them/their histories/

> +
> +The names of refs that are fetched, together with the object names
> +they point at, are written to `.git/FETCH_HEAD`.  This information
> +is used by a later merge operation done by 'git merge'.  In addition,

Isn't this merge stuff about pull, not fetch?

> +the remote-tracking branches may be updated (see description on
> +<refspec> below for details).

I realize that "may be updated" is strictly correct, in that if the remote's
branches have not changed since the last fetch then the local tracking
branches won't change.

But it took me a second or two to think of that.  The "may" kindof tripped me
up.  The fact is that the local tracking branches are always updated to match
the remote's branches, it's just that sometimes the remote's branches don't
change.  So I think it would be clearer to say

	the remote-tracking branches are updated

because this makes it clear that the command always makes your local tracking
branches match the remote's.

		M.

> +
> +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,
>  or from several repositories at once if <group> is given and
> 

Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec

[Marc Branchaud]

On 14-05-29 06:42 PM, Junio C Hamano wrote:
> While it is not *wrong* per-se to say that pulling a rewound/rebased
> branch will lead to an unnecessary merge conflict, that is not what
> the leading "+" sign to allow non-fast-forward update of remote-tracking
> branch is at all.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/pull-fetch-param.txt | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
> index 18cffc2..2a7e2b7 100644
> --- a/Documentation/pull-fetch-param.txt
> +++ b/Documentation/pull-fetch-param.txt
> @@ -24,15 +24,15 @@ 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
> +the tip of it will not be descendant of the commit that
> +used to be at its tip the last time you fetched it and
> +stored in your remote-tracking branch.  You would want

I think the second part of that last sentence might be clearer as

	it is expected that its new tip will not be a descendant of
	its previous tip (as stored in your remote-tracking branch
	the last time you fetched).

Then start the next sentence with

	In this case, you would want ....


		M.

> +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]
> 

Re: [PATCH 1/5] fetch doc: update introductory part for clarity

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> On 14-05-29 06:42 PM, Junio C Hamano wrote:
>>  - "Branches" is a more common way to say "heads" in these days.
>> 
>>  - Remote-tracking branches are used a lot more these days and it is
>>    worth mentioning that it is one of the primary side effects of
>>    the command to update them.
>> 
>>  - Avoid "X. That means Y."  If Y is easier to understand to
>>    readers, just say that upfront.
>> 
>>  - Use of explicit refspec to fetch tags does not have much to do
>>    with turning "auto following" on or off.  It is a way to fetch
>>    tags that otherwise would not be fetched by auto-following.
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>>  Documentation/git-fetch.txt | 29 ++++++++++++++++-------------
>>  1 file changed, 16 insertions(+), 13 deletions(-)
>> 
>> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
>> index 5809aa4..d5f5b54 100644
>> --- a/Documentation/git-fetch.txt
>> +++ b/Documentation/git-fetch.txt
>> @@ -17,20 +17,23 @@ SYNOPSIS
>>  
>>  DESCRIPTION
>>  -----------
>> -Fetches named heads or tags from one or more other repositories,
>> -along with the objects necessary to complete them.
>> -
>> -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
>> +Fetch branches and/or tags (collectively, "refs") from one or more
>> +other repositories, along with the objects necessary to complete the
>> +histories of them.
>
> Phrasing: s/the histories of them/their histories/

Yeah, thanks.

>> +
>> +The names of refs that are fetched, together with the object names
>> +they point at, are written to `.git/FETCH_HEAD`.  This information
>> +is used by a later merge operation done by 'git merge'.  In addition,
>
> Isn't this merge stuff about pull, not fetch?

It is true that "git pull" uses "git fetch" and .git/FETCH_HEAD is a
documented mechanism between the two to communicate what commits the
latter downloaded are to be merged by the former, and that is one of
the reasons why we had the description here in the original before
this patch.  A user can also do this to refer to the tip of the
single branch she fetched:

	git fetch origin master
        git log -p ..FETCH_HEAD
        git merge FETCH_HEAD

Perhaps "is used ... by 'git merge'" can be rephrased somehow, like
"can be used to refer to what was fetched"?  Or we could go in the
opposite direction and be more explicit, i.e.

	"git pull" calls "git fetch" internally, and this
	information is used by the former to learn what commits were
	fetched by the latter.

I dunno.

>> +the remote-tracking branches may be updated (see description on
>> +<refspec> below for details).
>
> I realize that "may be updated" is strictly correct, in that if the remote's
> branches have not changed since the last fetch then the local tracking
> branches won't change.
>
> But it took me a second or two to think of that.  The "may" kindof tripped me
> up.  The fact is that the local tracking branches are always updated to match
> the remote's branches, it's just that sometimes the remote's branches don't
> change.  So I think it would be clearer to say
>
> 	the remote-tracking branches are updated
>
> because this makes it clear that the command always makes your local tracking
> branches match the remote's.

The primary reason behind my "may be" was not "they may not have
done anything in the meantime", but was "we may not have configured
to track at all", but in that case by definition we don't have "the
remote-tracking branches", so now I realize that it is pointless to
say "may be updated".

Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

>> +When the remote branch you want to fetch is known to
>> +be rewound and rebased regularly, it is expected that
>> +the tip of it will not be descendant of the commit that
>> +used to be at its tip the last time you fetched it and
>> +stored in your remote-tracking branch.  You would want
>
> I think the second part of that last sentence might be clearer as
>
> 	it is expected that its new tip will not be a descendant of
> 	its previous tip (as stored in your remote-tracking branch
> 	the last time you fetched).

Yeah, that reads better.  Thanks.

>
> Then start the next sentence with
>
> 	In this case, you would want ....

I somehow find that "in this case" redundant, given that "for such
branches" already limits the scope of the suggestion.  I dunno.

>> +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]
>> 

Re: [PATCH 1/5] fetch doc: update introductory part for clarity

[Marc Branchaud]

On 14-05-30 01:52 PM, Junio C Hamano wrote:
> Marc Branchaud <marcnarc@xiplink.com> writes:
> 
>> On 14-05-29 06:42 PM, Junio C Hamano wrote:
>>> +
>>> +The names of refs that are fetched, together with the object names
>>> +they point at, are written to `.git/FETCH_HEAD`.  This information
>>> +is used by a later merge operation done by 'git merge'.  In addition,
>>
>> Isn't this merge stuff about pull, not fetch?
> 
> It is true that "git pull" uses "git fetch" and .git/FETCH_HEAD is a
> documented mechanism between the two to communicate what commits the
> latter downloaded are to be merged by the former, and that is one of
> the reasons why we had the description here in the original before
> this patch.  A user can also do this to refer to the tip of the
> single branch she fetched:
> 
> 	git fetch origin master
>         git log -p ..FETCH_HEAD
>         git merge FETCH_HEAD
> 
> Perhaps "is used ... by 'git merge'" can be rephrased somehow, like
> "can be used to refer to what was fetched"?  Or we could go in the
> opposite direction and be more explicit, i.e.
> 
> 	"git pull" calls "git fetch" internally, and this
> 	information is used by the former to learn what commits were
> 	fetched by the latter.
> 
> I dunno.

Y'know, I've always been a bit confused by FETCH_HEAD, especially if the
fetch updates several remote-tracking branches.

The docs say that all the fetched refs are written to FETCH_HEAD (perhaps a
more accurate name would have been FETCH_HEADS?).  If that's truly the case,
it seems weird to use FETCH_HEAD in log and merge commands.  (My FETCH_HEAD
file currently has 1434 lines in it -- what does that mean, and what does it
imply for those log and merge commands?)

Perhaps FETCH_HEAD shouldn't be mentioned at all in the introductory part of
fetch's man page.

		M.

Re: [PATCH 1/5] fetch doc: update introductory part for clarity

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> The docs say that all the fetched refs are written to FETCH_HEAD (perhaps a
> more accurate name would have been FETCH_HEADS?).  If that's truly the case,
> it seems weird to use FETCH_HEAD in log and merge commands.  (My FETCH_HEAD
> file currently has 1434 lines in it -- what does that mean, and what does it
> imply for those log and merge commands?)

The "fetch" that was run by "pull" would have arranged the single
remote ref that your "pull" merged to your then-current branch to
the very beginning of FETCH_HEAD, so "git log FETCH_HEAD" would show
the line of development from that ref, and "git merge FETCH_HEAD"
would also merge what your "pull" would have merged.

> Perhaps FETCH_HEAD shouldn't be mentioned at all in the introductory part of
> fetch's man page.

A possible downside is that unreasonable people can use the lack
of mention of FETCH_HEAD as an excuse to start making noises about
removing the feature.

Also, a natural way to peek into somebody else's history without
making a permanent damage to your own repository, is:

    $ git fetch $repository_of_marc master && git log FETCH_HEAD

As such a one-shot fetch from a random place does not use (and does
not want to use) any remote-tracking branch, knowing that FETCH_HEAD
is available for such a purpose would help people who want to script
such a thing.

[PATCH] fetch doc: Move FETCH_HEAD material, and add an example.

[Marc Branchaud]

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/git-fetch.txt | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

This patch applies on top of your 1/5.  It:

* De-emphasizes the FETCH_HEAD stuff by moving it to the end of the
  DESCRIPTION section,

* States that remote-tracking branches are simply "updated", and hints
  that playing with <refspec> can control this.

* Includes the "their histories" rephrasing.

* Adds your peek-at-a-remote-branch example.

If you like this, feel free to sqush it into your 1/5.

		M.


diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index d5f5b54..06106b9 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -18,14 +18,9 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Fetch branches and/or tags (collectively, "refs") from one or more
-other repositories, along with the objects necessary to complete the
-histories of them.
-
-The names of refs that are fetched, together with the object names
-they point at, are written to `.git/FETCH_HEAD`.  This information
-is used by a later merge operation done by 'git merge'.  In addition,
-the remote-tracking branches may be updated (see description on
-<refspec> below for details).
+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
@@ -35,7 +30,7 @@ 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]).
@@ -43,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[]
@@ -79,6 +78,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
 ----
-- 
2.0.0.1.g335f86d.dirty

Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec

[Marc Branchaud]

On 14-05-30 01:54 PM, Junio C Hamano wrote:
> Marc Branchaud <marcnarc@xiplink.com> writes:
>>
>> Then start the next sentence with
>>
>> 	In this case, you would want ....
> 
> I somehow find that "in this case" redundant, given that "for such
> branches" already limits the scope of the suggestion.  I dunno.

I shrug in indifference.  Toh-may-toe, poh-tah-toe...

		M.

Re: [PATCH] fetch doc: Move FETCH_HEAD material, and add an example.

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
> ---
>  Documentation/git-fetch.txt | 30 +++++++++++++++++++++---------
>  1 file changed, 21 insertions(+), 9 deletions(-)
>
> This patch applies on top of your 1/5.  It:
>
> * De-emphasizes the FETCH_HEAD stuff by moving it to the end of the
>   DESCRIPTION section,

This reads much better.  Thanks.

>
> * States that remote-tracking branches are simply "updated", and hints
>   that playing with <refspec> can control this.
>
> * Includes the "their histories" rephrasing.
>
> * Adds your peek-at-a-remote-branch example.

> If you like this, feel free to sqush it into your 1/5.

Will splice in as patch 1.5 instead ;-)