[PATCH/RFC v2] Documentation: flesh out “git pull” description

[PATCH/RFC v2] Documentation: flesh out “git pull” description

[Jonathan Nieder]

The current description in the pull man page does not say much more
than that “git pull” is fetch + merge.  Though that is all a person
needs to know in the end, it would be useful to summarize a bit about
what those commands do for new readers.

Most of this description is taken from the “git merge” docs.

Now that we explain how to back out of a failed merge (reset --merge),
we can tone down the warning against that a bit.

Except, as Thomas noticed, there’s a risk with that because people
might read this version of the manpage online and then conclude that
it is safe to try a merge with uncommitted changes, only to find that
their “git reset” doesn't support --merge yet.  Or worse, verify that
their git-reset has --merge by a quick test (1b5b465 is in 1.6.2) but
then find that it does not help with backing out of a merge (e11d7b5
is only in 1.7.0!).  For the master copy of the documentation on
kernel.org (but not the historical versions) we should keep the
warning.

So abuse the staledocs[] macro (currently used to suppress the Note in
git.html about previous versions of documentation) to distinguish
these cases.

Noticed-by: Geoff Russell <geoffrey.russell@gmail.com>
Improved-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Improved-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Changes since v1[1]:

 - remove a stray article
 - stop lying in the synopsis
 - use an ifdef to allow the warning about situations that may be difficult to
   recover from to be kept when building the "universal" docs that should
   apply to git versions before 1.7, too.

Junio: ideally for this to work, git-pull.html would need to get the
same special treatment as git.html gets.  Does that seem doable?  Is
Meta/dodoc.sh still the script to do it?

[1] http://thread.gmane.org/gmane.comp.version-control.git/151799/focus=151801

 Documentation/git-pull.txt |   70 +++++++++++++++++++++++++++++++++++++-------
 1 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10..54e9619 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,77 @@ git-pull - Fetch from and merge with another repository or a local branch
 
 SYNOPSIS
 --------
-'git pull' <options> <repository> <refspec>...
+'git pull' [options] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
 -----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
 
-Note that you can use `.` (current directory) as the
-<repository> to pull from the local repository -- this is useful
-when merging local branches into the current branch.
+Incorporates changes from a remote repository into the current
+branch.  In its default mode, `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
 
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1].  <refspec> can name an
+arbitrary remote ref (for example, the name of a tag) or even
+a collection of refs with corresponding remote tracking branches
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
+the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C master on origin
+         /
+    D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `master` (i.e., `E`)
+until its current commit (`C`) on top of `master` and record the
+result in a new commit along with the names of the two parent commits
+and a log message from the user describing the changes.
+
+------------
+          A---B---C remotes/origin/master
+         /         \
+    D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+ifndef::stalenotes[]
+To cancel a conflicting merge, use `git reset --merge`.
+endif::stalenotes[]
+ifdef::stalenotes[]
+
+In git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`.  *Warning*: In older versions of git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+in a state that may be hard to back out of in the case of a conflict.
+endif::stalenotes[]
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
 
 OPTIONS
 -------
 
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
-- 
1.7.2.1.544.ga752d.dirty

[PATCH/RFC v2 resend] Documentation: flesh out “git pull” description

[Jonathan Nieder]

The current description in the pull man page does not say much more
than that “git pull” is fetch + merge.  Though that is all a person
needs to know in the end, it would be useful to summarize a bit about
what those commands do for new readers.

Most of this description is taken from the “git merge” docs.

Now that we explain how to back out of a failed merge (reset --merge),
we can tone down the warning against that a bit.

Except, as Thomas noticed, there’s a risk with that because people
might read this version of the manpage online and then conclude that
it is safe to try a merge with uncommitted changes, only to find that
their “git reset” doesn't support --merge yet.  Or worse, verify that
their git-reset has --merge by a quick test (1b5b465 is in 1.6.2) but
then find that it does not help with backing out of a merge (e11d7b5
is only in 1.7.0!).  For the master copy of the documentation on
kernel.org (but not the historical versions) we should keep the
warning.

So abuse the staledocs[] macro (currently used to suppress the Note in
git.html about previous versions of documentation) to distinguish
these cases.

Noticed-by: Geoff Russell <geoffrey.russell@gmail.com>
Improved-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Improved-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
[misspelled an email address.  sorry for the noise!]

Changes since v1[1]:

 - remove a stray article
 - stop lying in the synopsis
 - use an ifdef to allow the warning about situations that may be difficult to
   recover from to be kept when building the "universal" docs that should
   apply to git versions before 1.7, too.

Junio: ideally for this to work, git-pull.html would need to get the
same special treatment as git.html gets.  Does that seem doable?  Is
Meta/dodoc.sh still the script to do it?

[1] http://thread.gmane.org/gmane.comp.version-control.git/151799/focus=151801

 Documentation/git-pull.txt |   70 +++++++++++++++++++++++++++++++++++++-------
 1 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10..54e9619 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,77 @@ git-pull - Fetch from and merge with another repository or a local branch
 
 SYNOPSIS
 --------
-'git pull' <options> <repository> <refspec>...
+'git pull' [options] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
 -----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
 
-Note that you can use `.` (current directory) as the
-<repository> to pull from the local repository -- this is useful
-when merging local branches into the current branch.
+Incorporates changes from a remote repository into the current
+branch.  In its default mode, `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
 
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1].  <refspec> can name an
+arbitrary remote ref (for example, the name of a tag) or even
+a collection of refs with corresponding remote tracking branches
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
+the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C master on origin
+         /
+    D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `master` (i.e., `E`)
+until its current commit (`C`) on top of `master` and record the
+result in a new commit along with the names of the two parent commits
+and a log message from the user describing the changes.
+
+------------
+          A---B---C remotes/origin/master
+         /         \
+    D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+ifndef::stalenotes[]
+To cancel a conflicting merge, use `git reset --merge`.
+endif::stalenotes[]
+ifdef::stalenotes[]
+
+In git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`.  *Warning*: In older versions of git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+in a state that may be hard to back out of in the case of a conflict.
+endif::stalenotes[]
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
 
 OPTIONS
 -------
 
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
-- 
1.7.2.1.544.ga752d.dirty

Re: [PATCH/RFC v2] Documentation: flesh out “git pull” description

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Junio: ideally for this to work, git-pull.html would need to get the
> same special treatment as git.html gets.  Does that seem doable?  Is
> Meta/dodoc.sh still the script to do it?

I am a bit reluctant to see stalenotes[] being abused; that ugly hack is
in effect _only_ while k.org documentation is being built to hang the "You
are reading the latest dev version, newer than anything released" sign on
the front door.

People with older git have documentation shipped with their versions, no?

Re: [PATCH/RFC v2] Documentation: flesh out “git pull” description

[Thomas Rast]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
> 
> > Junio: ideally for this to work, git-pull.html would need to get the
> > same special treatment as git.html gets.  Does that seem doable?  Is
> > Meta/dodoc.sh still the script to do it?
> 
> I am a bit reluctant to see stalenotes[] being abused; that ugly hack is
> in effect _only_ while k.org documentation is being built to hang the "You
> are reading the latest dev version, newer than anything released" sign on
> the front door.
> 
> People with older git have documentation shipped with their versions, no?

The problem is that google invariably turns up the 'master' docs at
k.org when you look for a git commmand (and that we point people to
them all the time on #git).  Hence I suggested not outright removing
this safety warning from the docs that even people running 1.5.x will
read.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH/RFC v2] Documentation: flesh out “git pull” description

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

> Junio C Hamano wrote:
>> Jonathan Nieder <jrnieder@gmail.com> writes:
>> 
>> > Junio: ideally for this to work, git-pull.html would need to get the
>> > same special treatment as git.html gets.  Does that seem doable?  Is
>> > Meta/dodoc.sh still the script to do it?
>> 
>> I am a bit reluctant to see stalenotes[] being abused; that ugly hack is
>> in effect _only_ while k.org documentation is being built to hang the "You
>> are reading the latest dev version, newer than anything released" sign on
>> the front door.
>> 
>> People with older git have documentation shipped with their versions, no?
>
> The problem is that google invariably turns up the 'master' docs at
> k.org when you look for a git commmand (and that we point people to
> them all the time on #git).  Hence I suggested not outright removing
> this safety warning from the docs that even people running 1.5.x will
> read.

I think the longer "In git 1.7.0 or later" with "Warning: in olden days"
can appear in everybody's version without causing any harm.  That way, it
is shown even to somebody who came to docs/v1.7.3/git-pull.html at k.org
from sideways.

[PATCH] Documentation: flesh out “git pull” description

[Jonathan Nieder]

The current description in the pull man page does not say much more
than that “git pull” is fetch + merge.  Though that is all a person
needs to know in the end, it would be useful to summarize a bit about
what those commands do for new readers.

Most of this description is taken from the “git merge” docs.

Now that we explain how to back out of a failed merge (reset --merge),
we can tone down the warning against that a bit.

Except, as Thomas noticed, there’s a risk with that because people
might read this version of the manpage online and then conclude that
it is safe to try a merge with uncommitted changes, only to find that
their “git reset” doesn't support --merge yet.  Or worse, verify that
their git-reset has --merge by a quick test (1b5b465 is in 1.6.2) but
then find that it does not help with backing out of a merge (e11d7b5
is only in 1.7.0!).  So keep the warning.

With clarifications from Ævar, Thomas, and Junio.

Noticed-by: Geoff Russell <geoffrey.russell@gmail.com>
Cc: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Junio C Hamano wrote:

> I think the longer "In git 1.7.0 or later" with "Warning: in olden days"
> can appear in everybody's version without causing any harm.  That way, it
> is shown even to somebody who came to docs/v1.7.3/git-pull.html at k.org
> from sideways.

Ok.  Here’s what it looks like with that change.

 Documentation/git-pull.txt |   65 ++++++++++++++++++++++++++++++++++++-------
 1 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10..7e72961 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,72 @@ git-pull - Fetch from and merge with another repository or a local branch
 
 SYNOPSIS
 --------
-'git pull' <options> <repository> <refspec>...
+'git pull' [options] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
 -----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
 
-Note that you can use `.` (current directory) as the
-<repository> to pull from the local repository -- this is useful
-when merging local branches into the current branch.
+Incorporates changes from a remote repository into the current
+branch.  In its default mode, `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
 
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1].  <refspec> can name an
+arbitrary remote ref (for example, the name of a tag) or even
+a collection of refs with corresponding remote tracking branches
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
+the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C master on origin
+         /
+    D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `master` (i.e., `E`)
+until its current commit (`C`) on top of `master` and record the
+result in a new commit along with the names of the two parent commits
+and a log message from the user describing the changes.
+
+------------
+          A---B---C remotes/origin/master
+         /         \
+    D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+
+In git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`.  *Warning*: In older versions of git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+in a state that may be hard to back out of in the case of a conflict.
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
 
 OPTIONS
 -------
 
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
-- 
1.7.2.1.544.ga752d.dirty