Re: [PATCH 00/59] Split config.txt
On Sat, Oct 20, 2018 at 5:39 AM 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. 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
Re: [PATCH 00/59] Split config.txt
On Sun, Oct 21, 2018 at 1:29 AM Junio C Hamano wrote: > > Ævar Arnfjörð Bjarmason 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/$some/$gro" 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..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
Re: [PATCH 00/59] Split config.txt
Ævar Arnfjörð Bjarmason 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/$some/$gro" 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..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.
Re: [PATCH 00/59] Split config.txt
On Sat, Oct 20 2018, Duy Nguyen wrote: > On Sat, Oct 20, 2018 at 9:25 PM Ævar Arnfjörð Bjarmason > 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 `, without ``, instead of creating a new branch from HEAD, if there exists a tracking branch in exactly one remote matching the basename of ``, 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.
Re: [PATCH 00/59] Split config.txt
On Sat, Oct 20, 2018 at 9:25 PM Ævar Arnfjörð Bjarmason 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... -- Duy
Re: [PATCH 00/59] Split config.txt
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?
[PATCH 00/59] Split config.txt
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 +