Bug: wrong documentation for git-fast-import's option command

Bug: wrong documentation for git-fast-import's option command

[Tomi Belan]

The man page of git-fast-import says the syntax is "'option' SP
<option> LF". But this is wrong, and commands like that will be
silently ignored.

fast-import.c only parses commands starting with "option git ", and
ignores others starting with "option ". See
https://github.com/git/git/blob/027a3b943b444a3e3a76f9a89803fc10245b858f/fast-import.c#L3487-L3490
.

The correct syntax is e.g. "option git stats" or "option git
big-file-threshold=123". The docs should say "'option' SP 'git' SP
<option> LF" or maybe even "'option' SP 'git' SP <option> ('='
<argument>)? LF" (similarly to the docs for feature), and explain this
is meant to allow other consumers of the fast import format.

Looks like this bug existed since the option command was added in
9c8398f in 2009. Am I the first one who tried to use it? ;-)

Cheers,

Tomi

Re: Bug: wrong documentation for git-fast-import's option command

[Andreas Schwab]

On Apr 30 2017, Tomi Belan <tomi.belan@gmail.com> wrote:

> The man page of git-fast-import says the syntax is "'option' SP
> <option> LF". But this is wrong, and commands like that will be
> silently ignored.

Unless <option> starts with 'git', as you have seen.  Other importers
may recognize other options, eg 'option hg ...'.

> The correct syntax is e.g. "option git stats" or "option git
> big-file-threshold=123". The docs should say "'option' SP 'git' SP
> <option> LF" or maybe even "'option' SP 'git' SP <option> ('='
> <argument>)? LF" (similarly to the docs for feature), and explain this
> is meant to allow other consumers of the fast import format.
>
> Looks like this bug existed since the option command was added in
> 9c8398f in 2009. Am I the first one who tried to use it? ;-)
>
> Cheers,
>
> Tomi
>

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Bug: wrong documentation for git-fast-import's option command

[Tomi Belan]

On Sun, Apr 30, 2017 at 12:21 PM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> Unless <option> starts with 'git', as you have seen.  Other importers
> may recognize other options, eg 'option hg ...'.

Hmm? Are you disagreeing with how I described the issue, or saying
there is no issue at all? I'm not sure.

I know the syntax is meant for other importers, which might accept
different options. My point is that the man page doesn't say anything
about that. If a frontend follows the man page and just prints e.g.
"option quiet", git-fast-import will silently ignore it.

If you dislike my suggested fix "'option' SP 'git' SP ...", then how about
'option' SP <program> SP <option> ('=' <argument>)? LF
and saying that for options supported by Git, <program> must be 'git'?

Cheers,

Tomi