[PATCH] Documentation/git-merge.txt: weaken warning about uncommited changes

[PATCH] Documentation/git-merge.txt: weaken warning about uncommited changes

[Matthieu Moy]

Commit 35d2fffd introduced 'git merge --abort' as a synonym to 'git reset
--merge', and added some failing tests in t7611-merge-abort.sh (search
'###' in this file) showing that 'git merge --abort' could not always
recover the pre-merge state.

Still, in many cases, 'git merge --abort' just works, and it is usually
considered that the ability to start a merge with uncommited changes is
an important property of Git.

Weaken the warning by discouraging only merge with /non-trivial/
uncommited changes.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
This is a followup to an old discussion:

http://thread.gmane.org/gmane.comp.version-control.git/221069

I don't think documenting all the failure cases in the doc would be a
good idea, so I've left the "in some cases" part.

 Documentation/git-merge.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 67ca99c..8c7f2f6 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -56,8 +56,8 @@ especially if those changes were further modified after the merge
 was started), 'git merge --abort' will in some cases be unable to
 reconstruct the original (pre-merge) changes. Therefore:
 
-*Warning*: Running 'git merge' with uncommitted changes is
-discouraged: while possible, it leaves you in a state that is hard to
+*Warning*: Running 'git merge' with non-trivial uncommitted changes is
+discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
 
-- 
1.8.3.1.495.g13f33cf.dirty

Re: [PATCH] Documentation/git-merge.txt: weaken warning about uncommited changes

[Ramkumar Ramachandra]

Matthieu Moy wrote:
> Weaken the warning by discouraging only merge with /non-trivial/
> uncommited changes.
>
> I don't think documenting all the failure cases in the doc would be a
> good idea, so I've left the "in some cases" part.

It's already documented in the pre-merge checks section, as Jonathan
pointed out [1].  We should update the documentation to point to it: I
do not think "non-trivial" is much of an improvement.

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

Re: [PATCH] Documentation/git-merge.txt: weaken warning about uncommited changes

[Matthieu Moy]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Matthieu Moy wrote:
>> Weaken the warning by discouraging only merge with /non-trivial/
>> uncommited changes.
>>
>> I don't think documenting all the failure cases in the doc would be a
>> good idea, so I've left the "in some cases" part.
>
> It's already documented in the pre-merge checks section, as Jonathan
> pointed out [1]. 

I had missed this one. But that's not the only case, you may also have
problems with renames. The complete list would be really long to have
here, and won't bring much to the user.

> We should update the documentation to point to it: I do not think
> "non-trivial" is much of an improvement.

Actually, I think it essentially says it all. If your changes are
important enough to deserve a real backup, you should stash or commit.
If you're ready to take the risk of losing it (the risk is small, but
does exist), it's OK to run "git merge" blindly.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH] Documentation/git-merge.txt: weaken warning about uncommited changes

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Ramkumar Ramachandra <artagnon@gmail.com> writes:
>
>> Matthieu Moy wrote:
>>> Weaken the warning by discouraging only merge with /non-trivial/
>>> uncommited changes.
>>>
>>> I don't think documenting all the failure cases in the doc would be a
>>> good idea, so I've left the "in some cases" part.
>>
>> It's already documented in the pre-merge checks section, as Jonathan
>> pointed out [1]. 
>
> I had missed this one. But that's not the only case, you may also have
> problems with renames. The complete list would be really long to have
> here, and won't bring much to the user.

True.

After having re-read the thread up to the message from Jonathan, I
suspect that a "merge" half of "pull --autosquash" series (which had
to be dropped) was based on a misunderstanding and we didn't have to
have that discussion if the documentation were a little less
discouraging about merging in a dirty working tree?

>> We should update the documentation to point to it: I do not think
>> "non-trivial" is much of an improvement.
>
> Actually, I think it essentially says it all. If your changes are
> important enough to deserve a real backup, you should stash or commit.
> If you're ready to take the risk of losing it (the risk is small, but
> does exist), it's OK to run "git merge" blindly.

Your documentation update makes sure that we are less discouraging,
I think.  It does not have to be the only phrasing (hinting others
to try to come up with a beeter version if they are so inclined),
but it is going in the right direction.