Re: git pull (Re: need advice on usage patterns)

[Thomas Rast <trast@student.ethz.ch>]

Jonathan Nieder wrote:
> +Incorporates changes from a remote repository into the current
> +branch.  In its default mode, a `git pull` is shorthand for
> +`git fetch` followed by `git merge FETCH_HEAD`.

In my ears, "a `git pull` is..." sounds weird.  I would remove the
'a'.  But maybe it's just my non-native English hard(ly) at work...

> -*Warning*: Running 'git pull' (actually, the underlying 'git merge')
> -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.
[...]
> +See linkgit:git-merge[1] for details, including how conflicts
> +are presented and handled.  To cancel a conflicting merge,
> +use `git reset --merge`.
> +
> +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].

There's a slight risk with it 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!).

Then again, who reads these manpages anyway?  And we shouldn't let old
versions get in the way of having consistent and up-to-date docs.  So,

Acked-by: Thomas Rast <trast@student.ethz.ch>

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