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

[Jonathan Nieder <jrnieder@gmail.com>]

Thomas Rast wrote:

> In my ears, "a `git pull` is..." sounds weird.  I would remove the
> 'a'.

Good idea.

> Jonathan Nieder wrote:

>> -*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`.
[...]
>                       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,

Agh, surely we can do better.  Maybe:

	See linkgit:git-merge[1] for details, including how conflicts
	are presented and handled.

	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 uncommited changes is discouraged: while possible,
	it leaves you in a state that may be hard to back out of
	in the case of a conflict.
	else::stalenotes[]
	To cancel a conflicting merge, use `git reset --merge`.
	endif::stalenotes[]

with the appropriate corresponding change to todo:dodoc.sh.