Re: de-alphabetizing the documentation

[Junio C Hamano]

frede...@ofb.net writes:

> Hi Jonathan and Git developers,
>
> I poked around today and figured out how to reorder the command
> listings in the manual page, they are taken from git/command-list.txt
> so I just reorder the lines in that file (after disabling sorting in
> git/Documentation/cmd-list.perl).
>
> I haven't reordered the whole list yet. I could only get one computer
> friend to send me his subcommand frequencies from his shell history. I
> reordered the commands partly based on that, and partly based on their
> order of occurrence in the various tutorial man pages.

There are two good things about a list that is alphabetical.  One is
that you can scan with your eyes and a finger to find what you are
looking for more quickly.  The other is that it is mechanical so we
won't waste time on bickering whose frequency table is more correct,
whether frequency table is a good approach to derive a better order
(than, say, the order in which the commands appear in an every-day
workflow) to begin with.

I would say if we were departing from alphabetical order, we should
first declare that we are *not* looking for the best way to order
the list, so that people do not waste too much time bikeshedding.
Instead what we should aim for is to come up with _an_ order that is
not too unreasonable and settle as quickly as we can.

And from that point of view, what I saw in new-git.1.out, I found it
not so outrageously unreasonable ;-).

Re: de-alphabetizing the documentation

[frederik]

Hi Jonathan and Git developers,

I poked around today and figured out how to reorder the command
listings in the manual page, they are taken from git/command-list.txt
so I just reorder the lines in that file (after disabling sorting in
git/Documentation/cmd-list.perl).

I haven't reordered the whole list yet. I could only get one computer
friend to send me his subcommand frequencies from his shell history. I
reordered the commands partly based on that, and partly based on their
order of occurrence in the various tutorial man pages.

I'm attaching a preliminary patch (not ready to be applied) just to
make sure this is going to be OK with the maintainer (who is the
maintainer?) before I continue. I made it with "git format-patch".

It seems fairly straightforward, but please let me know if there are
any problems. By the way, the command I used to check that the new
command list contains all the original commands is as follows:

diff =(sort command-list.txt | grep -v '^#') =(git cat-file blob 
e1c26c1bb7e618f6f372d9a568e7cab75612d2db | grep -v '^#' | sort)

Thanks,

Frederick

On Tue, Jul 24, 2018 at 02:11:46PM -0700, Jonathan Nieder wrote:
> Hi,
> 
> frede...@ofb.net wrote:
> 
> > Next week I should have time to send you a patch with the manual page
> > reordered...
> 
> Yay!
> 
> >   although, unless you have a special 'diff' which can
> > detect when text has been moved from one place to another, I'm
> > guessing it would take you even longer to check the validity of the
> > patch than it would for me to create it.
> 
> Fortunately we have "git diff --color-moved".
> 
> > However, I'm happy to do this or whatever other small projects you
> > would like to delegate as far as improving readability of your
> > documentation. I just need to know what is likely to be accepted.
> 
> Starting with this one seems fine.  Maybe people on list will have
> ideas for followups on top, or maybe you'll have ideas for ways others
> can help you, or both. ;-)
> 
> Thanks again,
> Jonathan
> 
>From 7aabe1060eabee16fac239ce49b8f9749be11adb Mon Sep 17 00:00:00 2001
From: Frederick Eaton 
Date: Fri, 10 Aug 2018 18:54:28 -0700
Subject: [PATCH] First test of command reordering

---
 Documentation/cmd-list.perl |   2 +-
 command-list.txt| 107 +---
 2 files changed, 61 insertions(+), 48 deletions(-)

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 5aa73cfe4..62c32f58d 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 e1c26c1bb..94a15fd42 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,35 +43,83 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# August 2018: The list has been reordered for didactic purposes,
+# basically according to approximate usefulness / frequency of use /
+# order of use. This is to make it possible for a beginner to read the
+# manual page "straight through" and see the most important commands
+# first, rather than getting them in alphabetical order. 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 tutorial
+git-helpancillaryinterrogators  
complete
+git-config  ancillarymanipulators   
complete
+git-clone   mainporcelain   init
+git-initmainporcelain   init
 git-add mainporcelain   worktree
-git-am  mainporcelain
+git-commit  mainporcelain   history
+git-diffmainporcelain   history
+git-status  mainporcelain   info
+git-log mainporcelain   info
+git-branch  mainporcelain   history
+git-checkoutmainporcelain   history
+git-merge   mainporcelain   history
+gitkmainporcelain
+git-pullmainporcelain   remote
+git-fetch   mainporcelain   remote
+# From frequencies
+git-grepmainporcelain   info
+git-showmainporcelain   info
+git-pushmainporcelain   remote
+git-submodule   mainporcelain
+git-reset   mainporcelain   worktree
+git-cherry-pick  

Re: de-alphabetizing the documentation

[Jonathan Nieder]

Hi,

frede...@ofb.net wrote:

> Next week I should have time to send you a patch with the manual page
> reordered...

Yay!

>   although, unless you have a special 'diff' which can
> detect when text has been moved from one place to another, I'm
> guessing it would take you even longer to check the validity of the
> patch than it would for me to create it.

Fortunately we have "git diff --color-moved".

> However, I'm happy to do this or whatever other small projects you
> would like to delegate as far as improving readability of your
> documentation. I just need to know what is likely to be accepted.

Starting with this one seems fine.  Maybe people on list will have
ideas for followups on top, or maybe you'll have ideas for ways others
can help you, or both. ;-)

Thanks again,
Jonathan

Re: de-alphabetizing the documentation

[frederik]

Hello Jonathan,

Thank you for replying to me earlier. I just wanted to follow up on
this thread. Did you decide not to go with my proposal?

Next week I should have time to send you a patch with the manual page
reordered... although, unless you have a special 'diff' which can
detect when text has been moved from one place to another, I'm
guessing it would take you even longer to check the validity of the
patch than it would for me to create it.

However, I'm happy to do this or whatever other small projects you
would like to delegate as far as improving readability of your
documentation. I just need to know what is likely to be accepted.

Thanks,

Frederick

On Sat, Jul 07, 2018 at 06:09:26PM -0700, frede...@ofb.net wrote:
> Hi Jonathan,
> 
> If it's really just a matter of needing someone with a newcomer's
> perspective, then I'd be happy to look over the ordering of the git
> subcommands. You can run the command I provided to glean the frequency
> of each subcommand from your shell history, I'll look over the output
> and see if the ordering makes sense to me, and then you or someone
> else can rearrange the manual page to list the subcommands in this
> order. Is that a suitable plan?
> 
> Thanks,
> 
> Frederick
> 
> On Fri, Jul 06, 2018 at 04:47:15PM -0700, Jonathan Nieder wrote:
> > Hi,
> > 
> > Frederick Eaton wrote:
> > 
> > >   Unfortunately my contribution will have to be limited for the
> > > moment to making this suggestion, as I am extraordinarily busy. I hope
> > > it will not be too burdensome to add this item to your TODO list and
> > > keep it there until a willing volunteer comes along.
> > 
> > No problem.  If you have time to contribute later, we can wait. :)
> > 
> > > For what it's worth, I made extensive changes to the Arch Wiki Git
> > > article back in 2015, following an initial attempt of mine to
> > > understand various tutorials. It was the most prominent wiki-based Git
> > > documentation I could find at the time. The article has of course seen
> > > numerous improvements since then.
> > 
> > For reference: https://wiki.archlinux.org/index.php/git
> > 
> > > I don't think that it's really important to find a "best" ordering for
> > > commands or glossary terms; it's more a matter of finding someone who
> > > is willing to take responsibility for choosing a reasonable ordering.
> > > Presumably the head maintainer of this project could delegate the task
> > > to a qualified volunteer, not a newbie like myself but not necessarily
> > > someone with expert knowledge either.
> > 
> > I'd have to say, when I compare the troubles a new user and a
> > long-timer would run into, I conclude that the long-timers would be
> > more likely to produce worse documentation.  It is very difficult to
> > remember how new users see things.  The ideal skill set in fact has
> > nothing to do with level of Git expertise: to produce a good result, a
> > good technical writer would ask the right questions to gather
> > information from the experts and then test their documentation on
> > newcomers until it works well.
> > 
> > Based on the work you've described already having done, it sounds like
> > you'd be an ideal person to get this going, if you find yourself with
> > time for it.
> > 
> > >   It's too bad that a policy of
> > > not listing things alphabetically wasn't adopted from the beginning of
> > > this project, but I guess that's life.
> > 
> > From this thread I've been convinced that for this kind of reference
> > document, alphabetical organization within each section is a good
> > organization, provided each section is small enough (as in "git help"
> > output).
> > 
> > I'm also a fan of non reference documentation that can use a narrative
> > ordering instead (like "git help core-tutorial", except with more
> > modern commands).
> > 
> > > Thanks Eric for the pointer to "git help". This does indeed provide a
> > > finer and better grouping than the man-page (but it also looks like
> > > another candidate for de-alphabetization...!).
> > 
> > Indeed, copying that organization over from "git help" to the git(1)
> > manpage may be a good step for any interested people overhearing this
> > conversation.
> > 
> > As a first step, how about making git(1) recommend "git help", like
> > this?  It already recommends giteveryday(7) but the more interactive
> > first command might be useful for some people.
> > 
> > Thoughts?  Improvements?
> > 
> > -- >8 --
> > Subject: git doc: recommend "git help" as a starting point
> > 
> > The list of subcommands described in git(1) can be overwhelming.
> > Encourage newcomers to run "git help" to get a shorter list of
> > commands as a starting point.
> > 
> > Based on a suggestion by Frederick Eaton.
> > 
> > Signed-off-by: Jonathan Nieder 
> > ---
> >  Documentation/git.txt | 9 ++---
> >  1 file changed, 6 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/git.txt b/Documentation/git.txt
> > 

Re: de-alphabetizing the documentation

[frederik]

Hi Jonathan,

If it's really just a matter of needing someone with a newcomer's
perspective, then I'd be happy to look over the ordering of the git
subcommands. You can run the command I provided to glean the frequency
of each subcommand from your shell history, I'll look over the output
and see if the ordering makes sense to me, and then you or someone
else can rearrange the manual page to list the subcommands in this
order. Is that a suitable plan?

Thanks,

Frederick

On Fri, Jul 06, 2018 at 04:47:15PM -0700, Jonathan Nieder wrote:
> Hi,
> 
> Frederick Eaton wrote:
> 
> >   Unfortunately my contribution will have to be limited for the
> > moment to making this suggestion, as I am extraordinarily busy. I hope
> > it will not be too burdensome to add this item to your TODO list and
> > keep it there until a willing volunteer comes along.
> 
> No problem.  If you have time to contribute later, we can wait. :)
> 
> > For what it's worth, I made extensive changes to the Arch Wiki Git
> > article back in 2015, following an initial attempt of mine to
> > understand various tutorials. It was the most prominent wiki-based Git
> > documentation I could find at the time. The article has of course seen
> > numerous improvements since then.
> 
> For reference: https://wiki.archlinux.org/index.php/git
> 
> > I don't think that it's really important to find a "best" ordering for
> > commands or glossary terms; it's more a matter of finding someone who
> > is willing to take responsibility for choosing a reasonable ordering.
> > Presumably the head maintainer of this project could delegate the task
> > to a qualified volunteer, not a newbie like myself but not necessarily
> > someone with expert knowledge either.
> 
> I'd have to say, when I compare the troubles a new user and a
> long-timer would run into, I conclude that the long-timers would be
> more likely to produce worse documentation.  It is very difficult to
> remember how new users see things.  The ideal skill set in fact has
> nothing to do with level of Git expertise: to produce a good result, a
> good technical writer would ask the right questions to gather
> information from the experts and then test their documentation on
> newcomers until it works well.
> 
> Based on the work you've described already having done, it sounds like
> you'd be an ideal person to get this going, if you find yourself with
> time for it.
> 
> >   It's too bad that a policy of
> > not listing things alphabetically wasn't adopted from the beginning of
> > this project, but I guess that's life.
> 
> From this thread I've been convinced that for this kind of reference
> document, alphabetical organization within each section is a good
> organization, provided each section is small enough (as in "git help"
> output).
> 
> I'm also a fan of non reference documentation that can use a narrative
> ordering instead (like "git help core-tutorial", except with more
> modern commands).
> 
> > Thanks Eric for the pointer to "git help". This does indeed provide a
> > finer and better grouping than the man-page (but it also looks like
> > another candidate for de-alphabetization...!).
> 
> Indeed, copying that organization over from "git help" to the git(1)
> manpage may be a good step for any interested people overhearing this
> conversation.
> 
> As a first step, how about making git(1) recommend "git help", like
> this?  It already recommends giteveryday(7) but the more interactive
> first command might be useful for some people.
> 
> Thoughts?  Improvements?
> 
> -- >8 --
> Subject: git doc: recommend "git help" as a starting point
> 
> The list of subcommands described in git(1) can be overwhelming.
> Encourage newcomers to run "git help" to get a shorter list of
> commands as a starting point.
> 
> Based on a suggestion by Frederick Eaton.
> 
> Signed-off-by: Jonathan Nieder 
> ---
>  Documentation/git.txt | 9 ++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index dba7f0c18e..0149ce9af0 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -23,9 +23,12 @@ unusually rich command set that provides both high-level 
> operations
>  and full access to internals.
>  
>  See linkgit:gittutorial[7] to get started, then see
> -linkgit:giteveryday[7] for a useful minimum set of
> -commands.  The link:user-manual.html[Git User's Manual] has a more
> -in-depth introduction.
> +linkgit:giteveryday[7] and run
> +
> +git help
> +
> +for a useful minimum set of commands.  The link:user-manual.html[Git
> +User's Manual] has a more in-depth introduction.
>  
>  After you mastered the basic concepts, you can come back to this
>  page to learn what commands Git offers.  You can learn more about
> -- 
> 2.18.0.203.gfac676dfb9
> 

Re: de-alphabetizing the documentation

[Theodore Y. Ts'o]

On Fri, Jul 06, 2018 at 04:21:47PM -0700, frede...@ofb.net wrote:
> I don't think that it's really important to find a "best" ordering for
> commands or glossary terms; it's more a matter of finding someone who
> is willing to take responsibility for choosing a reasonable ordering.
> Presumably the head maintainer of this project could delegate the task
> to a qualified volunteer, not a newbie like myself but not necessarily
> someone with expert knowledge either. It's too bad that a policy of
> not listing things alphabetically wasn't adopted from the beginning of
> this project, but I guess that's life.

That wasn't that portion of the man page, for better or for worse.  We
can debate whethher using a non-alphabetical order would be better or
worse for everyone; personally, I think the much better pointer is at
the very beginning of the git man page, which points people at "man
gittutorial" and "man giteveryday".

It seems to me that for your stated goal, "git everyday" has a good
list of commands that people should learn, complete with a proposed
workflow.

That's probably the biggest stumbling block of finding an ideal
ordering.  What's reasonable really depends on your workflow, and
there are many different workflows depending on what a particular
developer is trying to do.  Consider carpentry; for some use cases, a
screwdriver is an absolutely critical tool.  For others, they might
never use it, and instead almost exclusively join two pieces of woods
using mortise and tenon joint.  Others might use a butt joint, plus
glue and nails.  All of these different techniques can be used to make
a wooden box, and they all involve a very different set of tools.

Regards,

- Ted

Re: de-alphabetizing the documentation

[Jonathan Nieder]

Hi,

Frederick Eaton wrote:

>   Unfortunately my contribution will have to be limited for the
> moment to making this suggestion, as I am extraordinarily busy. I hope
> it will not be too burdensome to add this item to your TODO list and
> keep it there until a willing volunteer comes along.

No problem.  If you have time to contribute later, we can wait. :)

> For what it's worth, I made extensive changes to the Arch Wiki Git
> article back in 2015, following an initial attempt of mine to
> understand various tutorials. It was the most prominent wiki-based Git
> documentation I could find at the time. The article has of course seen
> numerous improvements since then.

For reference: https://wiki.archlinux.org/index.php/git

> I don't think that it's really important to find a "best" ordering for
> commands or glossary terms; it's more a matter of finding someone who
> is willing to take responsibility for choosing a reasonable ordering.
> Presumably the head maintainer of this project could delegate the task
> to a qualified volunteer, not a newbie like myself but not necessarily
> someone with expert knowledge either.

I'd have to say, when I compare the troubles a new user and a
long-timer would run into, I conclude that the long-timers would be
more likely to produce worse documentation.  It is very difficult to
remember how new users see things.  The ideal skill set in fact has
nothing to do with level of Git expertise: to produce a good result, a
good technical writer would ask the right questions to gather
information from the experts and then test their documentation on
newcomers until it works well.

Based on the work you've described already having done, it sounds like
you'd be an ideal person to get this going, if you find yourself with
time for it.

>   It's too bad that a policy of
> not listing things alphabetically wasn't adopted from the beginning of
> this project, but I guess that's life.

>From this thread I've been convinced that for this kind of reference
document, alphabetical organization within each section is a good
organization, provided each section is small enough (as in "git help"
output).

I'm also a fan of non reference documentation that can use a narrative
ordering instead (like "git help core-tutorial", except with more
modern commands).

> Thanks Eric for the pointer to "git help". This does indeed provide a
> finer and better grouping than the man-page (but it also looks like
> another candidate for de-alphabetization...!).

Indeed, copying that organization over from "git help" to the git(1)
manpage may be a good step for any interested people overhearing this
conversation.

As a first step, how about making git(1) recommend "git help", like
this?  It already recommends giteveryday(7) but the more interactive
first command might be useful for some people.

Thoughts?  Improvements?

-- >8 --
Subject: git doc: recommend "git help" as a starting point

The list of subcommands described in git(1) can be overwhelming.
Encourage newcomers to run "git help" to get a shorter list of
commands as a starting point.

Based on a suggestion by Frederick Eaton.

Signed-off-by: Jonathan Nieder 
---
 Documentation/git.txt | 9 ++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index dba7f0c18e..0149ce9af0 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -23,9 +23,12 @@ unusually rich command set that provides both high-level 
operations
 and full access to internals.
 
 See linkgit:gittutorial[7] to get started, then see
-linkgit:giteveryday[7] for a useful minimum set of
-commands.  The link:user-manual.html[Git User's Manual] has a more
-in-depth introduction.
+linkgit:giteveryday[7] and run
+
+git help
+
+for a useful minimum set of commands.  The link:user-manual.html[Git
+User's Manual] has a more in-depth introduction.
 
 After you mastered the basic concepts, you can come back to this
 page to learn what commands Git offers.  You can learn more about
-- 
2.18.0.203.gfac676dfb9

Re: de-alphabetizing the documentation

[frederik]

Thank you Jonathan for signaling your willingness to adopt the
documentation philosophy I suggested. That's a quite valuable first
step. Unfortunately my contribution will have to be limited for the
moment to making this suggestion, as I am extraordinarily busy. I hope
it will not be too burdensome to add this item to your TODO list and
keep it there until a willing volunteer comes along.

For what it's worth, I made extensive changes to the Arch Wiki Git
article back in 2015, following an initial attempt of mine to
understand various tutorials. It was the most prominent wiki-based Git
documentation I could find at the time. The article has of course seen
numerous improvements since then.

I don't think that it's really important to find a "best" ordering for
commands or glossary terms; it's more a matter of finding someone who
is willing to take responsibility for choosing a reasonable ordering.
Presumably the head maintainer of this project could delegate the task
to a qualified volunteer, not a newbie like myself but not necessarily
someone with expert knowledge either. It's too bad that a policy of
not listing things alphabetically wasn't adopted from the beginning of
this project, but I guess that's life.

Thanks Eric for the pointer to "git help". This does indeed provide a
finer and better grouping than the man-page (but it also looks like
another candidate for de-alphabetization...!).

Many thanks,

Frederick

On Fri, Jul 06, 2018 at 02:18:28PM -0700, Jonathan Nieder wrote:
> Jonathan Nieder wrote:
> 
> > Ideas?  If you start with a proposal, we're happy to help refine it.
> > People in the #git channel on irc.freenode.net (wechat.freenode.net)
> > might also be useful for inspiration in coming up with a proposal.
> 
> I meant to link to webchat.freenode.net.  But
> https://kiwiirc.com/nextclient/ may have been a better link to use
> anyway.
> 
> Thanks and sorry for the noise,
> Jonathan
> 

On Fri, Jul 06, 2018 at 05:32:39PM -0400, Eric Sunshine wrote:
> On Fri, Jul 06, 2018 at 02:16:00PM -0700, Jonathan Nieder wrote:
> > Frederick Eaton wrote:
> > > I wonder if someone familiar with Git could list the commands in an
> > > order which makes more sense for learning, for example in the order in
> > > which they were invented by Git developers,
> > 
> > Alas, there are plenty of "Main porcelain commands", and I think that
> > is where your question comes from.  It would be nicer to list just five
> > to start, say.
> 
> "git help" makes some attempt at narrowing the list of porcelain
> commands likely to be used on an everyday basis (and it categorizes
> the list by general activity). Of the 21 commands listed, I use 14-16
> in pretty much every development session, so "git help" might be a
> good starting place for someone trying to figure out which commands to
> study, or for someone wishing to help focus the documentation a bit
> more for beginners.
> 
> --- >8 ---
> $ git help
> usage: git ...
> 
> These are common Git commands used in various situations:
> 
> start a working area (see also: git help tutorial)
>clone  Clone a repository into a new directory
>init   Create an empty Git repository or reinitialize an existing one
> 
> work on the current change (see also: git help everyday)
>addAdd file contents to the index
>mv Move or rename a file, a directory, or a symlink
>reset  Reset current HEAD to the specified state
>rm Remove files from the working tree and from the index
> 
> examine the history and state (see also: git help revisions)
>bisect Use binary search to find the commit that introduced a bug
>grep   Print lines matching a pattern
>logShow commit logs
>show   Show various types of objects
>status Show the working tree status
> 
> grow, mark and tweak your common history
>branch List, create, or delete branches
>checkout   Switch branches or restore working tree files
>commit Record changes to the repository
>diff   Show changes between commits, commit and working tree, etc
>merge  Join two or more development histories together
>rebase Reapply commits on top of another base tip
>tagCreate, list, delete or verify a tag object signed with GPG
> 
> collaborate (see also: git help workflows)
>fetch  Download objects and refs from another repository
>pull   Fetch from and integrate with another repository or a local 
> branch
>push   Update remote refs along with associated objects
> 
> 'git help -a' and 'git help -g' list available subcommands and some
> concept guides. See 'git help ' or 'git help '
> to read about a specific subcommand or concept.
> --- >8 ---
> 

Re: de-alphabetizing the documentation

[Eric Sunshine]

On Fri, Jul 06, 2018 at 02:16:00PM -0700, Jonathan Nieder wrote:
> Frederick Eaton wrote:
> > I wonder if someone familiar with Git could list the commands in an
> > order which makes more sense for learning, for example in the order in
> > which they were invented by Git developers,
> 
> Alas, there are plenty of "Main porcelain commands", and I think that
> is where your question comes from.  It would be nicer to list just five
> to start, say.

"git help" makes some attempt at narrowing the list of porcelain
commands likely to be used on an everyday basis (and it categorizes
the list by general activity). Of the 21 commands listed, I use 14-16
in pretty much every development session, so "git help" might be a
good starting place for someone trying to figure out which commands to
study, or for someone wishing to help focus the documentation a bit
more for beginners.

--- >8 ---
$ git help
usage: git ...

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone  Clone a repository into a new directory
   init   Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   addAdd file contents to the index
   mv Move or rename a file, a directory, or a symlink
   reset  Reset current HEAD to the specified state
   rm Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect Use binary search to find the commit that introduced a bug
   grep   Print lines matching a pattern
   logShow commit logs
   show   Show various types of objects
   status Show the working tree status

grow, mark and tweak your common history
   branch List, create, or delete branches
   checkout   Switch branches or restore working tree files
   commit Record changes to the repository
   diff   Show changes between commits, commit and working tree, etc
   merge  Join two or more development histories together
   rebase Reapply commits on top of another base tip
   tagCreate, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch  Download objects and refs from another repository
   pull   Fetch from and integrate with another repository or a local branch
   push   Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help ' or 'git help '
to read about a specific subcommand or concept.
--- >8 ---

Re: de-alphabetizing the documentation

[Jonathan Nieder]

Jonathan Nieder wrote:

> Ideas?  If you start with a proposal, we're happy to help refine it.
> People in the #git channel on irc.freenode.net (wechat.freenode.net)
> might also be useful for inspiration in coming up with a proposal.

I meant to link to webchat.freenode.net.  But
https://kiwiirc.com/nextclient/ may have been a better link to use
anyway.

Thanks and sorry for the noise,
Jonathan

Re: de-alphabetizing the documentation

[Jonathan Nieder]

Hi Frederick,

Frederick Eaton wrote:

> I am trying to learn how to use Git but I've been put off by not
> knowing where to start. I would like to start with the 'git' man page,
> but it lists the Git subcommands in alphabetical order, rather than in
> an order which would be useful for learners. For example, I'm not sure
> how often 'git bisect' is used, but it is strange to see it listed
> before 'git init' and 'git clone'.
[...]
> I wonder if someone familiar with Git could list the commands in an
> order which makes more sense for learning, for example in the order in
> which they were invented by Git developers,

That doesn't seem like a useful order pedagogically, but

> or in the reverse order of
> frequency of use by a typical Git user.

That does.

Currently the commands are already broken into a few categories:

  High-level commands
Main porcelain commands
Ancillary commands
Interacting with others
  Low-level commands
Manipulation commands
Interrogation commands
Synching repositories
Internal helper commands

While it's alphabetical within each section, overall it is not
alphabetical at all!

Alas, there are plenty of "Main porcelain commands", and I think that
is where your question comes from.  It would be nicer to list just five
to start, say.

Some of the most thoughtful documentation that comes with Git is at
https://www.kernel.org/pub/software/scm/git/docs/user-manual.html.
It might be useful for inspiration.

Ideas?  If you start with a proposal, we're happy to help refine it.
People in the #git channel on irc.freenode.net (wechat.freenode.net)
might also be useful for inspiration in coming up with a proposal.

Each of us have our weaknesses for this kind of work: you're telling
me you're too new to have a sense of which commands are the first a
person would need to learn (and I have no reason to doubt you), while
many on this list would have the opposite problem of taking too much
for granted and not being able to put themselves in the mind of a
newcomer.  So we'll have to help each other.

tl/dr: if you come up with a proposed "first commands to learn"
category with some proposed commands to go in it, we'll be happy to
help you with the next steps.

[...]
> Finally, perhaps the same listing and/or reordering could be done for
> other important manual pages, like 'gitglossary'. Presumably
> 'gitglossary' should be sorted topologically, so that each term is
> defined prior to any terms depending on it.

Your help is welcome here as well.  Probably a similar kind of
categorization, with entries ordered either alphabetically or
according to some narrative in each section, would be the easiest to
maintain over time.

Thanks,
Jonathan

de-alphabetizing the documentation

[frederik]

Dear Git Developers,

I am trying to learn how to use Git but I've been put off by not
knowing where to start. I would like to start with the 'git' man page,
but it lists the Git subcommands in alphabetical order, rather than in
an order which would be useful for learners. For example, I'm not sure
how often 'git bisect' is used, but it is strange to see it listed
before 'git init' and 'git clone'.

I know that 'gittutorial' exists, and I've indeed worked through it
and some other Git tutorials. However, these are more like lists of
examples that should come at the end of a typical manual page. I don't
think they are intended as canonical references for the program
functionality. At some point I would like to use the main 'git' manual
page as my primary source of documentation. This would be easier if it
were designed to be read straight through.

I wonder if someone familiar with Git could list the commands in an
order which makes more sense for learning, for example in the order in
which they were invented by Git developers, or in the reverse order of
frequency of use by a typical Git user. This could easily be derived
from the shell history of someone who is reading this.

(cat ~/.bash_history; cut -d ";" -f 2 ~/.zsh_history) | grep '^git ' | cut 
-d ' ' -f 2 | sort | uniq -c | sort -nr

I would like to have this list for personal use, but once it is
created, perhaps someone could also add it to the main Git man page.
The list could be added at the top of the "GIT COMMANDS" section.
Alternatively, and I think preferably, the entries in that section
could be rearranged into this order.

Finally, perhaps the same listing and/or reordering could be done for
other important manual pages, like 'gitglossary'. Presumably
'gitglossary' should be sorted topologically, so that each term is
defined prior to any terms depending on it.

I'm not sure why alphabetical order was decided upon, but it seems
less than useful in the information age, when people can easily search
for text electronically. Maybe at some point someone decided to "clean
up" the presentation by alphabetizing the manual page. As a user who
is more concerned with substance, it is annoying to encounter such an
emphasis on the superficial, which seems unworthy of such an important
piece of software.

Thank you,

Frederick Eaton