Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 78 ยท Getting Started

Getting Help and Learning Git

Learn to find answers inside Git itself - git help, -h usage lines, command lists, a glossary of core terms, and how to read the most common Git error messages.

Nobody remembers every Git option. Git has over a hundred commands and each has dozens of flags. The people who look fluent are not memorizing; they know where to look and how to read what Git tells them. Git is unusually good at helping: it suggests corrections for typos, prints the next command to try, and ships with built-in documentation.

This lesson shows the built-in help system, how to read a usage line, a glossary of the words Git uses all the time, and how to decode the first error messages you will meet. It is the last lesson of the Getting Started chapter; afterwards Status, Diff and Seeing Changes starts the daily workflow.

On your own computer git help <command> opens the full manual page in a pager or browser. Our sandbox has no manual-page viewer and no browser, so the long manuals are shown as read-only text. The short -h usage summaries and all the error messages below are real output.

Three levels of help

Git gives you help at three depths. Use the cheapest one that answers your question.

You type You get When to use
git <command> -h A short usage summary and the list of options You know the command, forgot a flag
git help <command> (or git <command> --help) The complete manual page with examples You need details and examples
git help -g The list of concept guides You want to learn an idea, not a command

Short help with -h

-h works offline, instantly and in any terminal, and prints to the screen without a pager. Let us ask about git switch:

Bash Short usage with -h

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first line is the usage line. Learn to read its notation, because it is the same in every command:

Notation Meaning
<branch> A value you replace with your own
[<options>] Optional
[<branch>] Optional value
a | b Choose one
... after an item Can be repeated
-- Separator: everything after it is a file path, not an option

So usage: git switch [<options>] [<branch>] means you may pass options and a branch name, and both are optional. Lines under it describe each option. Long options such as --create have short forms such as -c; scripts should prefer the long form because it documents itself.

The full manual

git help status and git status --help open the manual page. On a typical computer it is formatted text in less (press q to quit, /word to search, space to page). The structure of a manual page is the same everywhere:

TEXT
NAME          one-line description
SYNOPSIS      every accepted form of the command
DESCRIPTION   what it does, in prose
OPTIONS       every flag, alphabetical or grouped
EXAMPLES      common recipes (often the most useful part)
CONFIGURATION which settings influence the command
SEE ALSO      related commands

Read SYNOPSIS to see forms, EXAMPLES to copy a recipe, and OPTIONS to find a flag. Here is what our sandbox does when you ask:

Bash No manual viewer in the sandbox (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The message fatal: no man viewer handled the request means Git looked for man and found nothing; on your machine it will just work. If you prefer a browser, git help --web status opens the HTML version, and git help --info uses the info format.

Concept guides

Besides commands, Git documents ideas. git help -g lists the guides, and git help <guide> opens one:

Bash The list of guides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Three pages are worth reading early: the everyday guide (a minimal set of daily commands), the glossary guide (definitions of Git's vocabulary) and git help revisions (how to name commits, which we cover in Revision Syntax). git help -a lists every command, grouped (porcelain for people, plumbing for scripts), and git help -c lists every configuration variable.

Bash How many commands and settings does Git have

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Do not be scared by the numbers: a normal day uses fewer than twenty commands. The list is grouped, and the first group, Main Porcelain Commands, is the one you need.

Git helps you when you mistype

Git suggests corrections for typos. When you type git statsu, it does not just fail:

Bash Misspelled command (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

You see git: 'statsu' is not a git command. See 'git --help'. followed by The most similar command is status. You can even let Git run the guess after a delay by setting help.autocorrect (for instance to prompt to be asked first); most people leave it off so that typos never run an unintended command.

A related feature is the tip many commands print after an unusual action. Messages that start with hint: are Git teaching you. They can be switched off with advice.* settings once you know them, but at the beginning, read them.

Reading Git's error messages

Git's errors fall into two types. error: or fatal: means the command did nothing (or stopped); warning: means it continued but you should look. Most errors say what went wrong and often what to do. Let us meet the commonest ones deliberately.

"not a git repository"

You ran a repository command outside any repository. Git looks in the current folder and every parent for a .git folder:

Bash Outside a repository (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The message fatal: not a git repository (or any parent up to mount point /) also mentions the filesystem boundary, because Git stops searching at the edge of the disk. The fix is to cd into the project or run git init. Exit code 128 is what Git uses for "fatal" errors.

"does not have any commits yet"

A fresh repository has no commits, so commands that need history fail:

Bash A repository with no commits (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git log says fatal: your current branch 'main' does not have any commits yet. That is not a bug; just make a commit first. git rev-parse HEAD prints the word HEAD and an "ambiguous argument" error, since HEAD points at a branch that does not exist yet.

"Author identity unknown"

You tried to commit without telling Git who you are. The message even shows the two commands to fix it: set user.name and user.email (Installing and Configuring Git).

Other messages you will meet soon

These happen once you work on branches or with remotes. The topic lessons explain them in depth; here is a map so you know where to look:

Message (shortened) Meaning Where to learn
nothing to commit, working tree clean All three areas agree Status and Diff
Your local changes would be overwritten by checkout Switching branches would lose edits Branches
CONFLICT (content): Merge conflict in ... Two changes touch the same lines Resolving Merge Conflicts
You are in 'detached HEAD' state You checked out a commit, not a branch Branches
rejected ... (non-fast-forward) The remote has commits you do not have push, pull and Tracking Branches
fatal: refusing to merge unrelated histories Two repositories with no common ancestor Troubleshooting

A glossary of the words Git uses

Git's own documentation uses precise words. Knowing them makes every message readable.

Term Meaning
repository (repo) The .git database plus the working tree it manages
working tree The files on disk that you edit
index / staging area The draft of the next commit
commit A snapshot with a message, author and parent(s)
hash / object ID The 40-character fingerprint that names a commit (or other object)
HEAD A pointer to the commit (usually via a branch) you currently have checked out
branch A movable label pointing at a commit
tag A fixed label pointing at a commit, usually for a release
remote Another repository your repository knows by name (typically origin)
clone A copy of a whole repository, with history
fetch / pull / push Download commits / download and combine / upload commits
merge Combine the history of two branches
rebase Replay commits on top of a different base
checkout / switch Move HEAD to a branch or commit and update the working tree
tracked / untracked Known / unknown to Git
clean / dirty Working tree matches / differs from the last commit
fast-forward Moving a branch label forward along a straight line, no new commit
ref A name (branch, tag, HEAD) that points to an object

You can find the official definitions in git help glossary.

Searching and learning efficiently

When the built-in help is not enough:

  • Search the manual by feature: git help -a | grep -i stash finds commands by name; git help -c | grep -i pull finds settings.
  • Use git status constantly. Its text changes with the situation (merge in progress, rebase in progress) and always suggests the commands that apply.
  • Search for the exact error text in quotes. Git's messages are stable across versions.
  • Prefer the official documentation (git-scm.com/docs and the free Pro Git book) over old blog posts, because Git has changed: git switch and git restore (2019) replaced many uses of the overloaded git checkout.
  • Experiment safely. Create a throwaway repository (as in every example here), make a mess and look at the result. Nothing is at risk.
Bash A throwaway playground in five lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The habit to build is simple: when unsure, run git status, read it, then git <command> -h, and try the command in a scratch repository before you try it on valuable work.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You forgot the name of a flag for git commit. What is the quickest way to see the options?

    git <command> -h prints a short usage summary with all options. Use git help <command> when you need the full manual with examples.
  2. 2. In a usage line, what does [<branch>] mean?

    Square brackets mark optional parts, angle brackets mark values you fill in, and ... means an item can repeat.
  3. 3. What does fatal: not a git repository (or any parent up to mount point /) tell you?

    Git searches upward from the current folder for .git. If it finds none, change into your project or run git init.
  4. 4. Which command lists Git's concept guides such as everyday and glossary?

    git help -g lists the guides. git help -a lists all commands and git help -c lists configuration variables.
  5. 5. What is a good first step when Git's output confuses you?

    git status describes the current state and suggests relevant commands. Destructive commands like reset --hard should never be a first reaction.

Summary

  • Use git <command> -h for a quick usage summary, git help <command> for the full manual, and git help -g for concept guides.
  • A usage line uses <value>, [optional], a | b and ...; -- separates options from paths.
  • git help -a lists commands and git help -c lists settings; our sandbox has no manual viewer, so read manuals on your own machine.
  • Git suggests the closest command when you mistype, and many messages start with hint:.
  • fatal means the command stopped, with exit code 128; read the message, which usually names the fix.
  • Learn the glossary words (working tree, index, HEAD, branch, remote, fast-forward) and use a throwaway repository to experiment.

Next: Status, Diff and Seeing Changes