Re: [PATCH] Document option --only of git commit

From: Pieter de Bie <pdebie@ai.rug.nl>
Date: Apr 18, 2008, 09:28 UTC
Message-ID: <9CE1A95F-941C-474F-9F18-1B01B73113B2@ai.rug.nl>
In-Reply-To: <1207827189-7509-2-git-send-email-johannes.sixt@telecom.at>

Hi,

On 10 apr 2008, at 13:33, Johannes Sixt wrote:

Show 7 quoted lines

> Its documentation was removed by  
> 6c96753df9db7f790a2ac4d95ec2a868394cd5ff,
> even though it is referenced from a few places, including builtin- 
> commit.c
> (as part of the commentary in the commit message template).
>
> Signed-off-by: Johannes Sixt <johannes.sixt@telecom.at>

Show 11 quoted lines

> +-o|--only::
> +	Make a commit only from the paths specified on the
> +	command line, disregarding any contents that have been
> +	staged so far. This is the default mode of operation of
> +	'git commit' if any paths are given on the command line,
> +	in which case this option can be omitted.
> +	If this option is specified together with '--amend', then
> +	no paths need be specified, which can be used to amend
> +	the last commit without committing changes that have
> +	already been staged.
> +

I find this addition to the manpage very confusing. If -o commits paths only from the command line, and it is also the default operation when run with paths, why is this text at the -o option? This behaviour is already documented in the description of git-commit:

        3. by listing files as arguments to the commit command, in  
which case the commit will
           ignore changes staged in the index, and instead record the  
current content of the
           listed files;

I'd suggest only using the second part (about --amend), or optionally adding something about what happens if you specify -o without --amend and without paths.

- Pieter