[PATCH] Prioritize list of commands appearing in git(1), via command-list.txt. Don't invoke 'sort' in Documentation/cmd-list.perl.
Signed-off-by: Frederick Eaton
---
Documentation/cmd-list.perl | 2 +-
command-list.txt| 295 +++-
2 files changed, 158 insertions(+), 139 deletions(-)
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 5aa73cfe45..62c32f58da 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -43,7 +43,7 @@ sub format_one {
}
my %cmds = ();
-for (sort <>) {
+for (<>) {
next if /^#/;
chomp;
diff --git a/command-list.txt b/command-list.txt
index 3a9af104b5..fb088dadea 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,164 +43,183 @@
# specified here, which can only have "guide" attribute and nothing
# else.
#
+# February 2019: This list had been sorted alphabetically but has been
+# reordered to make it easier for people to learn from the main git(1)
+# manual page. The new ordering is according to approximate usefulness
+# / frequency of use / order of use, with some grouping by topic. The
+# idea is to make it possible to read the manual page from beginning
+# to end and see the most important commands first, rather than
+# getting them in alphabetical order - in other words, to make the
+# manual page more like a table of contents and less like an index.
+# Please consider this when adding new commands.
+#
### command list (do not change this line, also do not change alignment)
# command name category [category] [category]
+# From gittutorial
+git-helpancillaryinterrogators
complete
+git-config ancillarymanipulators
complete
+git-clone mainporcelain init
+git-initmainporcelain init
git-add mainporcelain worktree
-git-am mainporcelain
-git-annotateancillaryinterrogators
-git-apply plumbingmanipulators
complete
-git-archimport foreignscminterface
-git-archive mainporcelain
-git-bisect mainporcelain info
-git-blame ancillaryinterrogators
complete
+git-commit mainporcelain history
+git-diffmainporcelain history
+git-status mainporcelain info
+git-log mainporcelain info
git-branch mainporcelain history
-git-bundle mainporcelain
-git-cat-fileplumbinginterrogators
-git-check-attr purehelpers
-git-check-ignorepurehelpers
-git-check-mailmap purehelpers
git-checkoutmainporcelain history
+git-merge mainporcelain history
+gitkmainporcelain
+git-pullmainporcelain remote
+git-fetch mainporcelain remote
+# From tutorial NEXT STEPS
+git-format-patchmainporcelain
+git-bisect mainporcelain info
+giteveryday guide
+gitworkflowsguide
+gitcvs-migrationguide
+# From giteveryday
+git-reset mainporcelain worktree
+git-rebase mainporcelain history
+git-tag mainporcelain history
+git-pushmainporcelain remote
+git-send-email foreignscminterface
complete
+git-request-pullforeignscminterface
complete
+git-am mainporcelain
+git-revert mainporcelain
+git-daemon synchingrepositories
+git-shell synchelpers
+git-http-backendsynchingrepositories
+gitweb ancillaryinterrogators
+# From user feedback
+git-grepmainporcelain info
+git-showmainporcelain info
+git-submodule mainporcelain
+git-cherry-pick mainporcelain
+git-clean mainporcelain
+# From gittutorial-2
+git-cat-fileplumbinginterrogators
+git-ls-tree plumbinginter
[PATCH 0/1] de-alphabetize command list
This is a follow-up to my proposal to de-alphabetize the command listings in the git(1) manual page, from 6 July 2018. Some projects have manual page items listed in alphabetical order, some don't. As I argued in my proposal, I find it easier to learn from material which is not alphabetized. If this patch is accepted, I hope that it will make the Git documentation more accessible to myself and others. I produced the reordered command list in this patch using several sources, as indicated by comments in the new command-list.txt file. First, all the commands in the main part of "gittutorial(7)" appear in order, then the commands in giteveryday(7). Then appear additional commands from a friend's shell history, in reverse order of frequency. Then gittutorial-2(7), then gitcore-tutorial(7). After that there is a list of "guides", followed by about 100 commands not appearing in the earlier lists. I kept the guides and the remaining commands in their category groupings (guide, mainporcelain, ancillarymanipulators, etc.), but ordered the commands within each category according to my own judgment after skimming each manual page. To verify that the new list is a permutation of the most recent list, I use the following command (it should produce no output and exit 0): diff <(git show master:command-list.txt | grep -v '^#' | sort ) <(cat command-list.txt | grep -v '^#' | sort) Note this patch changes the order of commands appearing in the generated file "command-list.h", which mostly seems to be used by "help.c". Probably due to the various occurrences of QSORT in "help.c", I think this reordering has no visible effect. I am willing to do any additional testing which may be recommended to ensure that this patch has no undesired consequences. Frederick Eaton (1): Prioritize list of commands appearing in git(1), via command-list.txt. Don't invoke 'sort' in Documentation/cmd-list.perl. Documentation/cmd-list.perl | 2 +- command-list.txt| 295 +++- 2 files changed, 158 insertions(+), 139 deletions(-) -- 2.20.1
[PATCH 3/3] git-describe.1: clarify that "human readable" is also git-readable
The caption uses the term "human readable", but the DESCRIPTION did not explain this in context. Signed-off-by: Frederick Eaton --- Documentation/git-describe.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e027fb8c4..ccdc5f83d 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -18,7 +18,9 @@ The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the -abbreviated object name of the most recent commit. +abbreviated object name of the most recent commit. The result +is a "human-readable" object name which can also be used to +identify the commit to other git commands. By default (without --all or --tags) `git describe` only shows annotated tags. For more information about creating annotated tags -- 2.19.0
[PATCH 2/3] git-column.1: clarify initial description, provide examples
When I read this man page I couldn't figure out what kind of input it was referring to, or how input was being put into columns, or where I should look for the syntax of the --mode option. Signed-off-by: Frederick Eaton --- Documentation/git-column.txt | 35 +-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 03d18465d..5bbb51068 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -13,7 +13,10 @@ SYNOPSIS DESCRIPTION --- -This command formats its input into multiple columns. +This command formats the lines of its standard input into a table with +multiple columns. Each input line occupies one cell of the table. It +is used internally by other git commands to format output into +columns. OPTIONS --- @@ -23,7 +26,7 @@ OPTIONS --mode=:: Specify layout mode. See configuration variable column.ui for option - syntax. + syntax (in git-config(1)). --raw-mode=:: Same as --mode but take mode encoded as a number. This is mainly used @@ -43,6 +46,34 @@ OPTIONS --padding=:: The number of spaces between columns. One space by default. +EXAMPLES +-- + +Format data by columns: + +$ seq 1 24 | git column --mode=column --padding=5 +1 4 7 10 13 16 19 22 +2 5 8 11 14 17 20 23 +3 6 9 12 15 18 21 24 + + +Format data by rows: + +$ seq 1 21 | git column --mode=row --padding=5 +1 2 3 4 5 6 7 +8 9 10 11 12 13 14 +15 16 17 18 19 20 21 + + +List some tags in a table with unequal column widths: + +$ git tag --list 'v2.4.*' --column=row,dense +v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3 +v2.4.1 v2.4.10 v2.4.11 v2.4.12 v2.4.2 +v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7 +v2.4.8 v2.4.9 + + GIT --- Part of the linkgit:git[1] suite -- 2.19.0
[PATCH 0/3] some documentation changes from the beginning of the alphabet
I've never sent patches using git before so I thought it would be useful to make a small test. I read ./Documentation/SubmittingPatches and I sent these to myself and practiced applying them using `git am`, and I also compiled and checked the revised manual pages to see that they format correctly. Unfortunately it was too late to run 'git diff --check' because I had already committed the changes to my repo, but I don't see any whitespace highlighted when I run 'git log -p'. I'm sure I'm doing something wrong, so please let me know what it is! Here's the command I'll use to send the messages (without --dry-run): git send-email --to "Junio C Hamano " --cc git@vger.kernel.org --cc-cmd ./contrib/contacts/git-contacts outgoing/ --dry-run By the way for some reason git-contacts shows more names when I run it on the patch hash than when I give it the patch name: $ ./contrib/contacts/git-contacts 222580cb60ee64f7b81fed64ec8fbfc81952557f Sébastien Guimmara Nguyễn Thái Ngọc Duy Eric Sunshine Junio C Hamano $ ./contrib/contacts/git-contacts ./outgoing/0002-git-column.1-clarify-initial-description-provide-exa.patch Junio C Hamano Not sure what's going on here, but the changes I propose seem fairly straightforward...(?) Frederick Eaton (3): git-archimport.1: specify what kind of Arch we're talking about git-column.1: clarify initial description, provide examples git-describe.1: clarify that "human readable" is also git-readable Documentation/git-archimport.txt | 5 +++-- Documentation/git-column.txt | 35 ++-- Documentation/git-describe.txt | 4 +++- 3 files changed, 39 insertions(+), 5 deletions(-) -- 2.19.0
[PATCH 1/3] git-archimport.1: specify what kind of Arch we're talking about
Is it a CPU architecture? Is it Arch Linux? If you search for "arch repository", nothing relevant comes up. Let's call it GNU Arch so people can find it with search engines. Signed-off-by: Frederick Eaton --- Documentation/git-archimport.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index ea7065336..a595a0ffe 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -3,7 +3,7 @@ git-archimport(1) NAME -git-archimport - Import an Arch repository into Git +git-archimport - Import a GNU Arch repository into Git SYNOPSIS @@ -14,7 +14,8 @@ SYNOPSIS DESCRIPTION --- -Imports a project from one or more Arch repositories. It will follow branches +Imports a project from one or more GNU Arch repositories. +It will follow branches and repositories within the namespaces defined by the parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it -- 2.19.0
