Help System

Git includes documentation that matches the installed version. Use it to verify syntax and behavior before relying on a command copied from another source.

1. Concise help and the full manual

For a quick synopsis and option list in the terminal:

git commit -h

For the complete manual:

git commit --help
git help commit

The last two forms are equivalent for normal use. On Git for Windows, the full manual may open as a local page in a browser. That is a display choice, not a difference in the documentation’s purpose.

Use concise help when you need to recall syntax or an option. Use the full manual when you need behavior, constraints, examples, or related concepts.

2. Reading a synopsis

Consider this synopsis:

git grep [<options>] [-e] <pattern> [<rev>...] [[--] <path>...]

Its notation communicates structure:

[item]    optional
<item>    placeholder to replace with a real value
item...   repeatable

Therefore, <pattern> is required, while options, revisions, and paths are optional. The ellipsis after a path means that more than one path may be given. Revision-based searching is covered later with history and revision selection.

3. Options and option values

Help often lists a short and a long name for the same option:

-n, --line-number
-i, --ignore-case

Either spelling selects the same behavior:

git grep -n "TODO"
git grep --line-number "TODO"

Multiple compatible options can be combined:

git grep -n -i "todo"

Some options require a value:

--max-depth <n>

Here, --max-depth is the option and 3 is its value:

git grep --max-depth 3 "UserService"

Notation such as --[no-]verify documents two forms:

--verify
--no-verify

4. Separating options from paths

The marker -- means that option parsing has ended. Anything after it is treated as a path:

git grep "database" -- src/ tests/

It is often optional when the command is unambiguous, but it makes intent clear and protects a path beginning with a dash from being interpreted as an option:

git grep "database" -- -config.php

5. Discovering a command

When the task is known but the command name is not, list the available commands:

git help -a

List conceptual guides with:

git help -g

After finding a likely command, inspect it before use:

git grep -h

Do not try to memorize every option. Find the command, inspect its synopsis, and read the description of the behavior you need.

6. Reading Git’s messages

Messages commonly identify their role:

error: the immediate problem
hint:  a possible next step
usage: the accepted command shape

An error such as the following says that the command was recognized but the option was not:

error: unknown option `line-numbers`

Inspect the command’s help and correct the spelling instead of trying unrelated commands. A hint is not an instruction that must be executed. Git cannot know your complete intent, repository policy, or recovery requirements.

If Git reports that the current directory is not a repository, first verify the location:

pwd
ls -la
git rev-parse --show-toplevel

Do not immediately run git init; doing so in the wrong directory creates a new repository instead of returning to the intended one.

7. Practical example

This read-only search ignores letter case and prints matching line numbers:

git grep -i -n "hello"

Example output:

y.txt:1:Hello

The command reads tracked content. It does not edit files, stage changes, or create commits.

8. Common mistakes

• Assuming -h lists every Git command instead of helping with one command.
• Treating [<options>] as exactly one option.
• Typing synopsis brackets or angle brackets literally.
• Confusing an option with the value that follows it.
• Assuming no terminal output from --help means it failed when a browser opened.
• Executing a hint without understanding its effect.
• Running git init before checking whether the current directory is correct.

9. Summary

git <command> -h       concise command help
git <command> --help   full command manual
git help <command>     full command manual
git help -a            available commands
git help -g            conceptual guides
--                     end option parsing

10. Knowledge check

1. What do square brackets mean in a synopsis?

The enclosed part is optional.

2. What does an ellipsis after a placeholder mean?

The preceding element can be repeated.

3. Why would you write – before a path?

It ends option parsing and makes clear that the remaining arguments are paths.

4. Must every line beginning with hint: be executed?

No. It is a suggestion whose effect must be understood and checked against the intended result.

5. Does git grep modify repository state?

No. It searches and reports matching content.