diff options
| author | Ævar Arnfjörð Bjarmason <avarab@gmail.com> | 2022-08-04 18:28:33 +0200 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2022-08-04 23:12:23 +0200 |
| commit | d976c5100fb5f55f648d8b400bcbda1116b82dec (patch) | |
| tree | ee65ead55c91dbbd75b44b52c9cf3ce0a6dce9af /command-list.txt | |
| parent | git help doc: use "<doc>" instead of "<guide>" (diff) | |
| download | git-d976c5100fb5f55f648d8b400bcbda1116b82dec.tar.xz git-d976c5100fb5f55f648d8b400bcbda1116b82dec.zip | |
git docs: add a category for user-facing file, repo and command UX
Create a new "Repository, command and file interfaces" section in the
main "git help git" manual page. Move things that belong under this
new criteria from the generic "Guides" section.
The "Guides" section was added in f442f28a81b (git.txt: add list of
guides, 2020-08-05). It makes sense to have e.g. "giteveryday(7)" and
"gitfaq(7)" listed under "Guides".
But placing e.g. "gitignore(5)" in it is stretching the meaning of
what a "guide" is, ideally that section should list things similar to
"giteveryday(7)" and "gitcore-tutorial(7)".
An alternate name that was considered for this new section was "User
formats", for consistency with the nomenclature used for man section 5
in general. My man(1) lists it as "File formats and conventions,
e.g. /etc/passwd".
So calling this "git help --formats" or "git help --user-formats"
would make sense for e.g. gitignore(5), but would be stretching it
somewhat for githooks(5), and would seem really suspect for the likes
of gitcli(7).
Let's instead pick a name that's closer to the generic term "User
interface", which is really what this documentation discusses: General
user-interface documentation that doesn't obviously belong elsewhere.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'command-list.txt')
| -rw-r--r-- | command-list.txt | 21 |
1 files changed, 13 insertions, 8 deletions
diff --git a/command-list.txt b/command-list.txt index 9bd6f3c48f..1d45303e14 100644 --- a/command-list.txt +++ b/command-list.txt @@ -43,6 +43,11 @@ # specified here, which can only have "guide" attribute and nothing # else. # +# User-facing repository, command and file interfaces such as +# documentation for the .gitmodules, .mailmap etc. files lives in man +# sections 5 and 7. These entries can only have the "userinterfaces" +# attribute and nothing else. +# ### command list (do not change this line) # command name category [category] [category] git-add mainporcelain worktree @@ -192,8 +197,8 @@ git-verify-tag ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -gitattributes guide -gitcli guide +gitattributes userinterfaces +gitcli userinterfaces gitcore-tutorial guide gitcredentials guide gitcvs-migration guide @@ -201,15 +206,15 @@ gitdiffcore guide giteveryday guide gitfaq guide gitglossary guide -githooks guide -gitignore guide +githooks userinterfaces +gitignore userinterfaces gitk mainporcelain -gitmailmap guide -gitmodules guide +gitmailmap userinterfaces +gitmodules userinterfaces gitnamespaces guide gitremote-helpers guide -gitrepository-layout guide -gitrevisions guide +gitrepository-layout userinterfaces +gitrevisions userinterfaces gitsubmodules guide gittutorial guide gittutorial-2 guide |