Why is Git a big deal?

What is “version control”, and why should you care? Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later […] a Version Control System (VCS) is a very wise thing to use. It allows you to revert selected files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more. Using a VCS also generally means that if you screw things up or lose files, you can easily recover […]

- Pro Git, sec 1.1

Git was originally designed around the needs of the Linux kernel¹, which (along with automatic configuration scripts and some documentation) adds up to 25 millon lines of code in 60 thousand files, and is under simultaneous development by 15 thousand developers².

However, Git has moved beyond the Linux kernel. Git succeeds so hard at its stated purpose that it has ended up underpinning all modern software development.

A good first impression

Getting help

If you didn't know anything about Git, you may try opening a terminal, typing git, and seeing what happens. If you had some experience using console commands, you may try something like git -h, git --help, git help, help git, man git, or info git. The first thing that Git does right is that almost all of these work.

git, git help, and git --help all print out the Git introduction page (we'll discuss this in a minute)
git -h prints a terse usage summary. It isn't very helpful, but it tells you about git --help
man git and info git open the Git manual page

help git doesn't work at all; this is due to technical reasons for which the Git developers can hardly be blamed.

Technical summary: help is a shell builtin in most shells (it prints out some help for your shell's commands). If Git provided a help command it would get hidden behind the builtin. Plus if different programs supplied their own, the shell would have to pick which one to call. Solving this would require help to be a single program installed everywhere, with each new software package registering new pages when it is installed, at which point we've reinvented man.

The Git introduction page

The intro page begins with a standard synopsis block, explaining how to call the program.

usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

The synopsis block is nearly useless to a novice, but it takes up little space, and displaying it first is the done thing in software.

Then comes this:

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)
   add               Add file contents to the index
   mv                Move or rename a file, a directory, or a symlink
   restore           Restore working tree files
   rm                Remove files from the working tree and from the index
   sparse-checkout   Initialize and modify the sparse-checkout

examine the history and state (see also: git help revisions)
   bisect            Use binary search to find the commit that introduced a bug
   diff              Show changes between commits, commit and working tree, etc
   grep              Print lines matching a pattern
   log               Show 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
   commit            Record changes to the repository
   merge             Join two or more development histories together
   rebase            Reapply commits on top of another base tip
   reset             Reset current HEAD to the specified state
   switch            Switch branches
   tag               Create, 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

Every commonly used command is listed, each one gets a single line description, and most importantly: commands are grouped into broad intentions. These intentions ("start a working area", "work on the current change", "examine the history and state", "grow, mark and tweak your common history", and "collaborate") are a good summary of what people actually do when interacting with Git.

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.

Finally, the intro page tells us how to get a comprehensive reference of commands, and how to get a list of the concept guides that come with the software.

The documentation you don't read

There are lots of Git commands, and each one has a wealth of configuration options. git push dedicates seven pages of documentation to options alone.

Nobody is supposed to read the whole thing before they start working. You read what you need, when you need it. Often you know that you need to know something because an error message is telling you so.

Error messages

Git does an excellent job of self-diagnosing in error messages, often providing a tentative fix.

For instance, if you try to commit a change without setting your username and email (which is almost certain) Git prints the following error:

Author identity unknown

*** Please tell me who you are.

Run

  git config --global user.email "you@example.com"
  git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.

When trying to merge two branches with incompatible changes:

CONFLICT (add/add): Merge conflict in y
Auto-merging y
Automatic merge failed; fix conflicts and then commit the result.

And if you type a non-existent command name, Git guesses what you mean (but does nothing):

git: 'swich' is not a git command. See 'git --help'.

The most similar command is
	switch

Problems

The Git docs do a whole lot impressively well, but they feel like they are a loose federation of independent documentation projects, rather than a unified whole:

You don't need a book to use Git, but there is one anyway. The book is freely available through a Creative Commons license, and is prominently displayed on the Git website, but the documentation included with the program makes no mention of it.
The Git manual page (man git or info git) conforms pretty strictly to conventional man page structure, leaning heavily towards the "reference" side. The man page does not tell you to go look at the intro page. This is a problem, because it is entirely possible a new user bumbles into this page, skipping the carefully curated intro page.
Between the man pages, concept guides, user's manual, and book, there is information for users at nearly any level of expertise, but the intro page does not make a point of immediately directing users to the most relevant resource. The user's manual and book are not even mentioned.
At least on Arch Linux at the time of this writing, there are missing files from the documentation (the notes section of the man page mentions /usr/share/doc/git-doc/*.html, which were not installed in my system). These are available through https://git-scm.com/docs, which is good; and the website is explicitly mentioned in the offline docs, which is excellent.

Why it works

Where Git's documentation system works, it shows awareness of and care for its audience. The main audience is catered to first, but nobody is left with nothing. Software developers in a hurry get a concise technical summary, but new users and readers looking to understand the inner workings of the program will know where to look for more.

References

Chacon, Scott, and Ben Straub. Pro Git. Apress, 2014. https://git-scm.com/book/en/v2.
Corbet, Jonathan, and Greg Kroah-Hartman. "Linux Kernel Development Report", 2017. https://www.linuxfoundation.org/wp-content/uploads/linux-kernel-report-2017.pdf.

Pro Git, sec1.2 ↩
Linux Kernel Development Report, p11 ↩