mbox series

[00/59] Split config.txt

Message ID 20181020123848.2785-1-pclouds@gmail.com
Headers show
Series Split config.txt | expand

Message

Duy Nguyen Oct. 20, 2018, 12:37 p.m. UTC
I started this a couple months back, moving a couple big config
sections out of config.txt to make it more manageable. This series
almost completes that. It moves all configs (except http.* which have
changes on 'pu') out of config.txt. config.txt is now about the
syntax, and a list of config sections. http section can be moved out
later.

I did a doc-diff on this series and the only change is ssh.variant is
moved down a bit to keep it in order, which is intended.

I thought of grouping all these config files in a separate directory
Documentation/config to avoid cluttering Documentation/ too much but
let's wait and see if people really find Documentation growing too
large first.

Nguyễn Thái Ngọc Duy (59):
  config.txt: move advice.* to a separate file
  config.txt: move core.* to a separate file
  config.txt: move add.* to a separate file
  config.txt: move alias.* to a separate file
  config.txt: move am.* to a separate file
  config.txt: move apply.* to a separate file
  config.txt: move blame.* to a separate file
  config.txt: move branch.* to a separate file
  config.txt: move browser.* to a separate file
  config.txt: move checkout.* to a separate file
  config.txt: move clean.* to a separate file
  config.txt: move color.* to a separate file
  config.txt: move column.* to a separate file
  config.txt: move commit.* to a separate file
  config.txt: move credential.* to a separate file
  config.txt: move completion.* to a separate file
  config.txt: move difftool.* to a separate file
  config.txt: move fastimport.* to a separate file
  config.txt: move filter.* to a separate file
  config.txt: move fsck.* to a separate file
  config.txt: move gc.* to a separate file
  config.txt: move gitweb.* to a separate file
  config.txt: move grep.* to a separate file
  config.txt: move gpg.* to a separate file
  config.txt: move guitool.* to a separate file
  config.txt: move help.* to a separate file
  config.txt: move ssh.* to a separate file
  config.txt: move i18n.* to a separate file
  config.txt: move i18n.* to a separate file
  config.txt: move init.* to a separate file
  config.txt: move instaweb.* to a separate file
  config.txt: move interactive.* to a separate file
  config.txt: move log.* to a separate file
  config.txt: move mailinfo.* to a separate file
  config.txt: move mailmap.* to a separate file
  config.txt: move man.* to a separate file
  config.txt: move mergetool.* to a separate file
  config.txt: move notes.* to a separate file
  config.txt: move pack.* to a separate file
  config.txt: move pager.* to a separate file
  config.txt: move pretty.* to a separate file
  config.txt: move protocol.* to a separate file
  config.txt: move remote.* to a separate file
  config.txt: move remotes.* to a separate file
  config.txt: move repack.* to a separate file
  config.txt: move rerere.* to a separate file
  config.txt: move sequencer.* to a separate file
  config.txt: move showBranch.* to a separate file
  config.txt: move splitIndex.* to a separate file
  config.txt: move status.* to a separate file
  config.txt: move tag.* to a separate file
  config.txt: move transfer.* to a separate file
  config.txt: move uploadarchive.* to a separate file
  config.txt: move uploadpack.* to a separate file
  config.txt: move url.* to a separate file
  config.txt: move user.* to a separate file
  config.txt: move versionsort.* to a separate file
  config.txt: move web.* to a separate file
  config.txt: move worktree.* to a separate file

 Documentation/add-config.txt           |    7 +
 Documentation/advice-config.txt        |   82 +
 Documentation/alias-config.txt         |   18 +
 Documentation/am-config.txt            |   14 +
 Documentation/apply-config.txt         |   11 +
 Documentation/blame-config.txt         |   21 +
 Documentation/branch-config.txt        |  102 +
 Documentation/browser-config.txt       |    9 +
 Documentation/checkout-config.txt      |   23 +
 Documentation/clean-config.txt         |    3 +
 Documentation/color-config.txt         |  201 ++
 Documentation/column-config.txt        |   55 +
 Documentation/commit-config.txt        |   29 +
 Documentation/completion-config.txt    |    7 +
 Documentation/config.txt               | 2640 +-----------------------
 Documentation/core-config.txt          |  594 ++++++
 Documentation/credential-config.txt    |   26 +
 Documentation/difftool-config.txt      |   14 +
 Documentation/fastimport-config.txt    |    8 +
 Documentation/filter-config.txt        |    9 +
 Documentation/fsck-config.txt          |   67 +
 Documentation/gc-config.txt            |  108 +
 Documentation/gitweb-config.txt        |   16 +
 Documentation/gpg-config.txt           |   20 +
 Documentation/grep-config.txt          |   24 +
 Documentation/guitool-config.txt       |   50 +
 Documentation/help-config.txt          |   23 +
 Documentation/i18n-config.txt          |   10 +
 Documentation/index-config.txt         |   10 +
 Documentation/init-config.txt          |    3 +
 Documentation/instaweb-config.txt      |   20 +
 Documentation/interactive-config.txt   |   16 +
 Documentation/log-config.txt           |   43 +
 Documentation/mailinfo-config.txt      |    6 +
 Documentation/mailmap-config.txt       |   15 +
 Documentation/man-config.txt           |   12 +
 Documentation/mergetool-config.txt     |   53 +
 Documentation/notes-config.txt         |   59 +
 Documentation/pack-config.txt          |  120 ++
 Documentation/pager-config.txt         |    8 +
 Documentation/pretty-config.txt        |    9 +
 Documentation/protocol-config.txt      |   64 +
 Documentation/remote-config.txt        |   78 +
 Documentation/remotes-config.txt       |    3 +
 Documentation/repack-config.txt        |   27 +
 Documentation/rerere-config.txt        |   12 +
 Documentation/sequencer-config.txt     |    5 +
 Documentation/showbranch-config.txt    |    3 +
 Documentation/splitindex-config.txt    |   24 +
 Documentation/ssh-config.txt           |   35 +
 Documentation/stash-config.txt         |    9 +
 Documentation/status-config.txt        |   72 +
 Documentation/tag-config.txt           |   16 +
 Documentation/transfer-config.txt      |   71 +
 Documentation/uploadarchive-config.txt |    6 +
 Documentation/uploadpack-config.txt    |   65 +
 Documentation/url-config.txt           |   30 +
 Documentation/user-config.txt          |   26 +
 Documentation/versionsort-config.txt   |   33 +
 Documentation/web-config.txt           |    4 +
 Documentation/worktree-config.txt      |    9 +
 61 files changed, 2608 insertions(+), 2549 deletions(-)
 create mode 100644 Documentation/add-config.txt
 create mode 100644 Documentation/advice-config.txt
 create mode 100644 Documentation/alias-config.txt
 create mode 100644 Documentation/am-config.txt
 create mode 100644 Documentation/apply-config.txt
 create mode 100644 Documentation/blame-config.txt
 create mode 100644 Documentation/branch-config.txt
 create mode 100644 Documentation/browser-config.txt
 create mode 100644 Documentation/checkout-config.txt
 create mode 100644 Documentation/clean-config.txt
 create mode 100644 Documentation/color-config.txt
 create mode 100644 Documentation/column-config.txt
 create mode 100644 Documentation/commit-config.txt
 create mode 100644 Documentation/completion-config.txt
 create mode 100644 Documentation/core-config.txt
 create mode 100644 Documentation/credential-config.txt
 create mode 100644 Documentation/difftool-config.txt
 create mode 100644 Documentation/fastimport-config.txt
 create mode 100644 Documentation/filter-config.txt
 create mode 100644 Documentation/fsck-config.txt
 create mode 100644 Documentation/gc-config.txt
 create mode 100644 Documentation/gitweb-config.txt
 create mode 100644 Documentation/gpg-config.txt
 create mode 100644 Documentation/grep-config.txt
 create mode 100644 Documentation/guitool-config.txt
 create mode 100644 Documentation/help-config.txt
 create mode 100644 Documentation/i18n-config.txt
 create mode 100644 Documentation/index-config.txt
 create mode 100644 Documentation/init-config.txt
 create mode 100644 Documentation/instaweb-config.txt
 create mode 100644 Documentation/interactive-config.txt
 create mode 100644 Documentation/log-config.txt
 create mode 100644 Documentation/mailinfo-config.txt
 create mode 100644 Documentation/mailmap-config.txt
 create mode 100644 Documentation/man-config.txt
 create mode 100644 Documentation/mergetool-config.txt
 create mode 100644 Documentation/notes-config.txt
 create mode 100644 Documentation/pack-config.txt
 create mode 100644 Documentation/pager-config.txt
 create mode 100644 Documentation/pretty-config.txt
 create mode 100644 Documentation/protocol-config.txt
 create mode 100644 Documentation/remote-config.txt
 create mode 100644 Documentation/remotes-config.txt
 create mode 100644 Documentation/repack-config.txt
 create mode 100644 Documentation/rerere-config.txt
 create mode 100644 Documentation/sequencer-config.txt
 create mode 100644 Documentation/showbranch-config.txt
 create mode 100644 Documentation/splitindex-config.txt
 create mode 100644 Documentation/ssh-config.txt
 create mode 100644 Documentation/stash-config.txt
 create mode 100644 Documentation/status-config.txt
 create mode 100644 Documentation/tag-config.txt
 create mode 100644 Documentation/transfer-config.txt
 create mode 100644 Documentation/uploadarchive-config.txt
 create mode 100644 Documentation/uploadpack-config.txt
 create mode 100644 Documentation/url-config.txt
 create mode 100644 Documentation/user-config.txt
 create mode 100644 Documentation/versionsort-config.txt
 create mode 100644 Documentation/web-config.txt
 create mode 100644 Documentation/worktree-config.txt

Comments

Ævar Arnfjörð Bjarmason Oct. 20, 2018, 7:25 p.m. UTC | #1
On Sat, Oct 20 2018, Nguyễn Thái Ngọc Duy wrote:

> I started this a couple months back, moving a couple big config
> sections out of config.txt to make it more manageable. This series
> almost completes that. It moves all configs (except http.* which have
> changes on 'pu') out of config.txt. config.txt is now about the
> syntax, and a list of config sections. http section can be moved out
> later.
>
> I did a doc-diff on this series and the only change is ssh.variant is
> moved down a bit to keep it in order, which is intended.
>
> I thought of grouping all these config files in a separate directory
> Documentation/config to avoid cluttering Documentation/ too much but
> let's wait and see if people really find Documentation growing too
> large first.

I had a slight bias against this when you started this, since I'm one of
these odd people who don't mind ~20k line files if the line count isn't
contributing to inherent complexity, e.g. in the case of config.txt you
could just use the search function all in one file.

But FWIW I've changed my mind to as strong opinion in favor this series,
because an actual annoyance of mine has been how inconsistently we
document config variables affecting individual commands.

I.e. in some cases we have somecmd.switch=xyz that's also a --switch
described in git-somecmd(1), and the --switch docs are more exhaustive,
or the other way around.

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?
Duy Nguyen Oct. 20, 2018, 7:30 p.m. UTC | #2
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...
Ævar Arnfjörð Bjarmason Oct. 20, 2018, 7:41 p.m. UTC | #3
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.
Junio C Hamano Oct. 20, 2018, 11:29 p.m. UTC | #4
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> I had a slight bias against this when you started this, since I'm one of
> these odd people who don't mind ~20k line files if the line count isn't
> contributing to inherent complexity, e.g. in the case of config.txt you
> could just use the search function all in one file.

After typing "less Documentation/config.txt" and realizing that I
have to open another file (which one?) to find how we described the
push.default config, I am already experiencing a lot stronger bias
against this.

But I know it will pass.  Once this ~60 patch series completes, my
irritation would peak, because at that point I would not be able to
even do "git grep push.config Documentation/config*", but I would no
longer be reaching for "less Documentation/config.txt" anymore at
that point.  Once Documentation/$group-config.txt (which I think is
a mistake) are renamed to Documentation/$something/$group.txt, then
I know I can do "less Doc<TAB>/$some<TAB>/$gro<TAB>" to get my ease
of use back.  There will still be an annoyance caused by having to
open another file when reading description of branch.<name>.merge in
branch-config.txt and seeing a reference to push.default, though.

And the end result makes it impossible to place a description of a
new variable in a wrong section.  It still is possible to mistakenly
insert a variable in a wrong place in the right section that
requires a fix like 8578037b ("config.txt: reorder blame stuff to
keep config keys sorted", 2018-08-04), but we do not fix all the
problems under the sky in one series ;-).

So after saying all of the above, I am moderately supportive of this
series.
Duy Nguyen Oct. 22, 2018, 2:42 p.m. UTC | #5
On Sun, Oct 21, 2018 at 1:29 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
> > I had a slight bias against this when you started this, since I'm one of
> > these odd people who don't mind ~20k line files if the line count isn't
> > contributing to inherent complexity, e.g. in the case of config.txt you
> > could just use the search function all in one file.
>
> After typing "less Documentation/config.txt" and realizing that I
> have to open another file (which one?) to find how we described the
> push.default config, I am already experiencing a lot stronger bias
> against this.
>
> But I know it will pass.  Once this ~60 patch series completes, my
> irritation would peak, because at that point I would not be able to
> even do "git grep push.config Documentation/config*", but I would no
> longer be reaching for "less Documentation/config.txt" anymore at
> that point.  Once Documentation/$group-config.txt (which I think is
> a mistake) are renamed to Documentation/$something/$group.txt,

I'll wait for js/mingw-http-ssl to land, move http.* out then rename
them all to Documentation/config/$group.txt then. I'll fix up makefile
dependencies then too.

> then
> I know I can do "less Doc<TAB>/$some<TAB>/$gro<TAB>" to get my ease
> of use back.  There will still be an annoyance caused by having to
> open another file when reading description of branch.<name>.merge in
> branch-config.txt and seeing a reference to push.default, though.
>
> And the end result makes it impossible to place a description of a
> new variable in a wrong section.  It still is possible to mistakenly
> insert a variable in a wrong place in the right section that
> requires a fix like 8578037b ("config.txt: reorder blame stuff to
> keep config keys sorted", 2018-08-04), but we do not fix all the
> problems under the sky in one series ;-).
>
> So after saying all of the above, I am moderately supportive of this
> series.
Stefan Beller Oct. 22, 2018, 7:22 p.m. UTC | #6
On Sat, Oct 20, 2018 at 5:39 AM Nguyễn Thái Ngọc Duy <pclouds@gmail.com> wrote:
>
> I started this a couple months back, moving a couple big config
> sections out of config.txt to make it more manageable. This series
> almost completes that. It moves all configs (except http.* which have
> changes on 'pu') out of config.txt. config.txt is now about the
> syntax, and a list of config sections. http section can be moved out
> later.
>
> I did a doc-diff on this series and the only change is ssh.variant is
> moved down a bit to keep it in order, which is intended.
>
> I thought of grouping all these config files in a separate directory
> Documentation/config to avoid cluttering Documentation/ too much but
> let's wait and see if people really find Documentation growing too
> large first.

Have you considered to use config as a prefix, i.e.
have config-add.txt instead of add-config.txt ?

currently any command is documented in a file
that is prefixed with "git-". There are others such as
gitcli or gitsubmodules, but as they lack the '-' they
surely are not about a command.

With the config- prefix it would be easier to sort and
cope with the individual files, and it would allow
grepping through Documentation/conf* (which may
be easier than Documentation/*conf* or similar)

I have no strong objection to the series as is
(I have not looked at any patch), but I would think
either a config directory or prefix may help further.

Stefan