Re: [PATCH/RFC v3 2/4] git-am.txt: add configuration section in git am documentation
- From
Matthieu Moy <matthieu.moy@grenoble-inp.fr>
- Date
- Jun 3, 2015, 16:21 UTC
- Message-ID
- <vpq4mmoep9y.fsf@anie.imag.fr>
- In-Reply-To
- <1433266446-2845-2-git-send-email-remi.lespinet@ensimag.grenoble-inp.fr>
Remi Lespinet <remi.lespinet@ensimag.grenoble-inp.fr> writes:
> Prepare a configuration section for the git am documentation.
Most git-*.txt do not have this CONFIGURATION section.
In an ideal world, we would have such section automatically generated (i.e. the description for each variable would exist in one place, and we would make sure that both "man git-config" and "man git-<command>" show it). In a really ideal world, it would also be propagated to the code and we would have a "git config --describe am.keepcr" or so that would return the doc.
I'm a bit worried to see documentation cut-and-pasted from config.txt to git-*.txt for maintainability: if the text on one side is modified, we're likely to forget the other and the text will diverge with time.
Not a strong objection, but I have the feeling that the more we do this kind of patches, the harder it will be if ever we decide to do the above.
Show 5 quoted lines
> +CONFIGURATION > +------------- > + > +am.keepcr:: > + If true, git-am will call git-mailsplit for patches in mbox format
`git am` `git mailsplit`
> + with parameter '--keep-cr'. In this case git-mailsplit will
Likewise
> + not remove `\r` from lines ending with `\r\n`. Can be overridden > + by giving '--no-keep-cr' from the command line.
That should be backquote, not forward-quote, right?
I know it's not your code since it's a cut-and-paste from config.txt, but that illustrates my point above: we used to have one place with wrong quotes, and we'd have two after the patch.
Show 14 quoted lines
> OPTIONS > ------- > (<mbox>|<Maildir>)...:: > @@ -43,11 +53,11 @@ OPTIONS > --keep-non-patch:: > Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). > > ---[no-]keep-cr:: > +--keep-cr:: > +--no-keep-cr:: > With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) > with the same option, to prevent it from stripping CR at the end of > - lines. `am.keepcr` configuration variable can be used to specify the > - default behaviour.
I don't think it's a good idea to remove this part. If I look for a way to make --keep-cr the default, the first place I'd look would be the doc for --keep-cr, and I'd appreciate a link to am.keepcr.
-- Matthieu Moy http://www-verimag.imag.fr/~moy/