Unhelpful Old Git

OK so Git is cool and its hip.

But Git help is actively an un-helpful, even spiteful, little bitch with man pages that insult more than the Git himself does.

You need to read the manual before you can read the help, some help manages to confuse simple concepts, and other help manages to skip over things that are not obvious but are important.

I could rant on this for ages but lets keep this simple, t his is the output from git help,  with my annotations and some highlights from man git-* which is all in the same vein.

The most commonly used git commands are:

   add        Add file contents to the index  // define "index" the word means many things,
                                              // why "Add file contents" and not "add a file"

   bisect     Find by binary search the change that introduced a bug   
        // does "by binary search" really help

   branch     List, create, or delete branches  // ok

   checkout   Checkout a branch or paths to the working tree
    // what is a "working tree" its not a thing that has "branches" is it perhaps :)
    // A working tree is a local working copy of a branch with perhaps a few changes,
    // IMHO the word tree just does not help
    // so a bit more help from...  

git help checkout

    "Updates files in the working tree to match the version in the index or the specified tree.
    If no paths are given, git checkout will also update HEAD to set the specified branch as the
    current branch." 

    // ?? confusing
    // presumably git checkout does what svn checkout does, simply

svn help checkout | head -1
checkout (co): checkout a working copy from a repository.

    // If it does not do that, I have not worked out from the help what it does do. 
    // When I got to "tree-ish" I gave up on the man page, WTF is a "tree-ish"

   clone      Clone a repository into a new directory          
    // Should this not say something like
    //  "Make a local copy of a remote remote repository and create a working copy"
    // so lets looks at the man page...

Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository (visible using git branch -r), and creates and checks out an initial branch that is forked from the cloned repository’s currently active branch. After the clone, a plain git fetch without arguments will update all the remote-tracking branches, and a git pull without arguments will in addition merge the remote master branch into the current master branch, if any. This default configuration is achieved by creating references to the remote branch heads under refs/remotes/origin and by initializing remote.origin.url and remote.origin.fetch configuration variables.

    // OH right, thanks man :)  I particularly like

"creates and checks out an initial branch that is forked from the cloned repository’s currently active branch."

    // instead of

"creates a working copy"

   commit     Record changes to the repository 
   // perhaps a mention of "local" here, since that is a distinguishing feature of git
   // perhaps some mention that the committed changes come from the "index" not the "working tree"

   diff       Show changes between commits, commit and working tree, etc   
   // "etc" really helps :)  I once bought a bottle of cheap wine that said

"Great with meat, cheese, fish, etc"

   fetch      Download objects and refs from another repository
   // lets mention "remote" here
   // and what is an object and what is a "ref"? we are trying to version control files, are we not?

   grep       Print lines matching a pattern
   // what does this add that grep -r does not do, or is this just grep -r ?
   // the only difference I can find is that git grep hangs after one page says END
   // and you have to Ctrl+c to continue

   init       Create an empty git repository or reinitialize an existing one 
   // shh don't mention the local thing

   log        Show commit logs     // finally something simple and accurate

   merge      Join two or more development histories together         
   // I have not worked out how to merge in git yet, supposedly git is good at merging
   // fuct-if-i-know-how(tm)  not sure what a development history is, a branch perhaps?

   mv         Move or rename a file, a directory, or a symlink     

   pull       Fetch from and merge with another repository or a local branch 
   // some commas please, this help should read
   // "pull   something you should never do, see fetch and merge"

   push       Update remote refs along with associated objects     
   // You what? This means nothing to me, and git push is important.
   // If you didn't know push synchronizes local commits with the remote repository
   // you would not guess from the help

   rebase     Forward-port local commits to the updated upstream head  
   // eh?

   reset      Reset current HEAD to the specified state                
   // what?
   rm         Remove files from the working tree and from the index    
   // This would be OK provided we agree on "working tree" and "index"

   show       Show various types of objects               
   // This "help" just fills a line with text, replace with "lorum ipsum   status     Show the working tree status               
    // This is a key command that should be used all the time,
    // and that description does not indicate what git status does.
    // git status lists all the files in your working copy that you have changed or added

   tag        Create, list, delete or verify a tag object signed with GPG  
    // Presumably this is a "label" surely "tag or label" is better than "tag object".
    // What meaning does object convey here?

You may not agree with all my comments above, and most are facetious, I admit, but I think you must agree that the help is unhelpful and perhaps we need to set up some charity organisation to help pay for the git's reform and re-introduction into polite society.

git-scm.org does not have a bug reporting mechanism, doh!

I'm not just complaining, I would gladly contribute better help for git, just as soon as I've worked out what the feck the little git is doing.

I realise that git tries its hardest to copy nothing from other SCM systems, but perhaps they should read the man from SVN and takes some tips.

If you have to use GIT I suggest you use google "git introduction" and go and read a tutorial or any piece of non-official documentation before you start trying to interpret the help.  Git is  sufficiently different to all other SCMs to merit a bit of research before making the jump.

There are lots and lots of web pages attempting to fill the void that is git help.

like this for example

http://help.github.com/git-cheat-sheets/