patchDocumentation: --amend cannot be combined with -c/-C/-F.

We used to get the following confusing error message:

% git commit --amend -a -m foo Option -m cannot be combined with -c/-C/-F

This is because --amend cannot be combined with -c/-C/-F, which makes sense, because they try to handle the same log message in different ways. So update the documentation to reflect this.

Signed-off-by: Peter Eriksen <s022018@student.dtu.dk>
---

This problem was reported by tko on #git. What do you think? It is not a "complete" fix, since --reuse, and --reedit have the same problem, but they are not even mentioned in the man page of git-commit.

 Documentation/git-commit.txt |    4 ++--
 git-commit.sh                |    6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

Peter Eriksen <s022018@student.dtu.dk> wrote:

Hmm.  The log-message options to git commit seem confused to me.

The default behaviour is to fire up an editor for the user to provide a message. The editor buffer may be pre-initialized, e.g., because MERGE_MSG exists.

This default behaviour can be overridden in a number of ways:

  * -m forces the message to be its argument;
  * -F forces the message to be the contents of some file;
  * -C forces the message to be a copy of some other commit message.

So far, so good. One can see why all of these options are mutually exclusive. The problem is in the mess of other options like -c and --amend.

Currently -c (copy some other commit message, and then edit it) is considered to be a `force message to be...' kind of option, like the others I've listed above.

So, for some reason, is --amend. This last is really annoying. I frequently find that I end up typing

  VISUAL=: git commit --amend ...

to fix the stupid thing I forgot to do before I committed last time. No, dammit, I don't want to mess with the editor.

Somewhere in all of this is a fairly nice, regular set of operations trying to escape. There are two processes at work:

  * setting a default message, and
  * maybe getting the user to edit it.

The first part is slightly complicated: there are a number of places to get a default message from, and several might be possible:

  * explicitly specified by the user (e.g., -m);
  * found lying about in MERGE_MSG;
  * picked up from the HEAD commit (for --amend); or
  * empty.

Choosing between MERGE_MSG and --amend is difficult; indeed, they probably ought to be mutually exclusive. But both should obviously win over an empty initial message, and (I think) just as obviously lose to an explicit message -- after all, the purpose of --amend is primarily to replace the current HEAD commit, not to fill in a default message.

-- [mdw]

Mark Wooding <mdw@distorted.org.uk> writes:

I think the mindset is a bit different. The -C/-c options are about the latter half of cherry-picking. The user asks "reuse the message from an existing commit so that I do not have to type", or "I could reuse the original log message almost as-is, but I am using the change in a slightly different context from the original commit (and that is why cherry-pick did not finish by itself and you need to run git-commit after fixing up), so I would need to talk a bit about what I did in the fix-up in the log message". Both are useful.

Amend is conflated -- you are amending what you did, either perhaps you found a small typo in the code in which case the difference between what is being amended and what will be committed may only be the tree and you would want to re-use an existing message as-is, or you found a small typo in the log message in which case there won't be any difference in the trees but you do want to spellfix the log message, or you may be fixing both.

We happen default to the edit behaviour for no particular reason, other than "because :q or C-x # are cheap".

Unfortunatly there is no good default for this case -- fixing tree and fixing message are both almost equally often used in the real world, so changing --amend not to let you edit by default and adding --edit option would inconvenience other use case.

Adding --no-edit option is not very nice either. It's almost as cumbersome to type as "EDITOR=:".

What you want might be an --amend-tree option; it would be to the --amend option what the -C (--reuse-message) option is to the -c (--reedit-message).

Junio C Hamano <junkio@cox.net> wrote:

Why not add --amend-tree and --amend-message (--amend is both in one)?. This would allow to amend the tree easily without changing the message and editing the message without caring for the current state of the index.