Overview
git records the history of a folder: every commit is a saved snapshot with a message, and you can go back, compare, branch off and merge. A folder with a history is a repository, kept in a hidden .git folder. Git works on your own computer without a network, and shares commits with other repositories (clone, fetch, push) when you ask. The examples create a repository in a temporary folder.
Background
git is an open-source tool whose documentation is at git-scm.com. It has many subcommands; this page covers the everyday ones and their output. The tool tested here is git 2.56.0.
Examples
Create a repository named main, and see that nothing is changed yet; the -q flags keep it quiet:
git init -q -b main && git status --short | wc -l | tr -d ' '
Stage a new file with git add; the status shows A for added:
git init -q -b main && printf hi > a.txt && git add a.txt && git status --short
Commit it with a message, and read the history; the name and address are given with -c so no setup is needed:
git init -q -b main && printf hi > a.txt && git add a.txt && git -c user.name=Demo -c user.email=demo@example.org commit -q -m first && git log --format=%s
See what changed since the last commit, as a summary:
git init -q -b main && printf 'a\n' > f && git add f && git -c user.name=D -c user.email=d@e.c commit -q -m one && printf 'b\n' >> f && git diff --stat | tail -n 1
Make a branch and switch to it, then ask which branch you are on:
git init -q -b main && git -c user.name=D -c user.email=d@e.c commit -q --allow-empty -m one && git switch -q -c feature && git branch --show-current
List several commit messages on one line, newest first:
git init -q -b main && git -c user.name=D -c user.email=d@e.c commit -q --allow-empty -m one && git -c user.name=D -c user.email=d@e.c commit -q --allow-empty -m two && git log --format=%s | paste -sd, -
Mark a commit with a tag, and list the tags:
git init -q -b main && git -c user.name=D -c user.email=d@e.c commit -q --allow-empty -m one && git tag v1 && git tag
Ask whether you are inside a repository, which is useful in scripts:
git init -q -b main && git rev-parse --is-inside-work-tree
Give a command a short name with a command alias; here st stands for status, set for this one call with -c:
git init -q -b main && git -c alias.st=status st --short | wc -l | tr -d ' '
Store a setting in the repository with git config, and read it back:
git init -q -b main && git config --local user.name Demo && git config --get user.name
Options
-C
Run as if started in this folder, as in git -C path status.
-c
Set a configuration value for this one command, as in -c user.name=Demo.
Aliases and configuration
Git keeps its settings in three layers: the repository (.git/config), your user (~/.gitconfig) and the system, and the nearest layer wins. git config --list --show-origin shows each setting and the file it comes from. A command alias is a setting named alias.NAME: git config --global alias.st status makes git st run git status. A value that starts with ! runs a shell command instead of a git command. This is separate from shell aliases, which belong to your shell and are not part of git.
Common mistakes
A commit needs a name and an email; if none is set, git commit stops and tells you to set them with git config. git add only stages: nothing is saved in history until git commit. Commands that rewrite history, such as git reset --hard, git clean -fd and git push --force, can destroy work and cannot always be undone; read what they will do first. Never commit passwords or keys: they stay in the history even after the file is removed. Old tutorials use master as the first branch name; the name is a setting, so say it with git init -b main.
Portability
git has one upstream, and the subcommands in this page behave the same on every system, but newer subcommands such as git switch and git restore need a recent version (git 2.23 or later). The examples were executed on git 2.56.0, in a temporary folder with a clean home folder, so your own settings do not change them. The Common examples were executed on git 2.56.0 (see the development guide for the exact check).
About upstream git
This is the upstream git command. It is one program everywhere; what differs between systems is its version and the settings in ~/.gitconfig.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.