Re: [PATCH 00/59] Split config.txt

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sat, Oct 20 2018, Duy Nguyen wrote:

> On Sat, Oct 20, 2018 at 9:25 PM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> wrote:
>> And sometimes like in the case of git-gc(1) we have gc.* config
>> documented in two places with different prose that needs to be updated
>> in two places in a CONFIGURATION section. This series allows us to just
>> unify the two and do an "include" in two places, and more generally have
>> the convention that a given command that uses configuration could have
>> that config both documented in git-config(1), and the same docs in its
>> own manpage.
>>
>> Is doing some post-cleanup like that your eventual goal after this
>> series?
>
> I did see the possibility of including command-specific config in
> individual command man page. But I'm not planning on doing it myself.
> Some command man page is already pretty long, plus sometimes we rely
> on the core.* part which should not be included in per-command man
> page...

I might follow-up with some of that after this lands then. We wouldn't
include all config (including core.*) that affects the command, but just
command-specific stuff like gc.* or worktree.*.

Due to limitations of ASCIIDOC link syntax we often just mention "blah
blah can be also configured as somecmd.config, see
linkgit:git-config[1]", e.g. one example I recently added is at:
https://git-scm.com/docs/git-fetch#_pruning

Then the user clicks on that, and ends up in this giant manpage and they
need to use their browser search. Both far that web experience and for
reading with "man" it would be nicer to be able to say "see the
CONFIGURATION section below" which would have that included.

But arguably better would be consistently being able to know where the
primary documentation is. E.g. for worktree.guessRemote (not picking on
you in particular, it was just easy because worktree.* is only one
config var) we have:

in git-config(1):

    worktree.guessRemote::
    	With `add`, if no branch argument, and neither of `-b` nor
    	`-B` nor `--detach` are given, the command defaults to
    	creating a new branch from HEAD.  If `worktree.guessRemote` is
    	set to true, `worktree add` tries to find a remote-tracking
    	branch whose name uniquely matches the new branch name.  If
    	such a branch exists, it is checked out and set as "upstream"
    	for the new branch.  If no such match can be found, it falls
    	back to creating a new branch from the current HEAD.

In git-worktree(1)

    --[no-]guess-remote::
    	With `worktree add <path>`, without `<commit-ish>`, instead
    	of creating a new branch from HEAD, if there exists a tracking
    	branch in exactly one remote matching the basename of `<path>`,
    	base the new branch on the remote-tracking branch, and mark
    	the remote-tracking branch as "upstream" from the new branch.
    +
    This can also be set up as the default behaviour by using the
    `worktree.guessRemote` config option.

Mostly they're saying the same, but all in different words, so you need
to carefully read both to really make sure you got it. There's many of
those cases, would be good if we could unify all or most of them.