| Message ID | 20181020123848.2785-1-pclouds@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Split config.txt | expand |
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?
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...
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.
Æ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.
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.
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