threads / bug / 45833

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

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

## tl;dr

3 messages between Apr 30, 2017 and May 1, 2017.

replies: 2people: 2as markdown or json

Tomi Belan· Apr 30, 2017, 00:07 UTC · lore

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

Andreas Schwab· Apr 30, 2017, 10:21 UTC · re: Tomi Belan · lore

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

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 ...'.

Show 13 quoted lines

> 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."

Tomi Belan· May 1, 2017, 13:26 UTC · re: Andreas Schwab · lore

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

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