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

From: Thomas Rast <trast@student.ethz.ch>
Date: Jul 26, 2010, 07:16 UTC
Message-ID: <201007260916.27306.trast@student.ethz.ch>
In-Reply-To: <20100726033634.GA30877@burratino>

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.

[...]

Show 8 quoted lines

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