In lesson 02-06 we learned to move around the history: git log with its formats, its filters by author and date, and searching with -S and -G. That was enough for a single-branch project with a handful of commits.

task-manager is now eight months old, with four active branches, merges, version tags and three people working on it. And the questions the team asks itself have changed in nature:

• What shape does the history have? What has been merged into main this month?
• What is in Carla's branch that is not in main, and the other way round?
• Who has contributed what, and how much?
• What are the milestones — tags and merges — without the noise of the intermediate commits?

And there is a second problem, more prosaic but just as real. The invocation from the previous lesson was git blame -w -C --date=short -L :normaliseText:app.js app.js. Nobody types that twice. The second half of this lesson is about that: turning the long commands you use daily into short words, with Git aliases.

1. --graph: seeing the shape of the history
2. --first-parent: the mainline, without noise
3. --simplify-by-decoration: the milestones only
4. --merges and --no-merges
5. Three-dot ranges and --left-right
6. Advanced --pretty=format:: colours and alignment
7. git shortlog: who has contributed what
8. Composing queries with what we have learned
9. Aliases: what they are and where they live
10. Aliases with !: shell and functions
11. A set of aliases for day-to-day work
12. Risks and good practice with aliases

By default git log gives a flat list ordered by date, which in a history with branches is misleading: you cannot see what came from where. --graph draws the DAG (lesson 03-01) with ASCII characters down the left-hand side.

The three modifiers are inseparable in practice:

How to read the drawing:

• Each * is a commit. The column it is in indicates its "lane".
• |\ marks a merge commit: two lines come into it.
• |/ marks the point at which two lanes join going backwards: the common ancestor.
• The fix/svg-delete branch appears hanging off 3f1a8d6 without having been merged: those are commits that exist only in that branch.

One detail about --decorate: since Git 2.13 it has been on by default when the output goes to a terminal (--decorate=auto), so you often do not need to type it. It can be pinned with:

And variants of --all that avoid the noise of dozens of old remote branches:

It has already come up in lesson 06-02 with bisect, and in 05-06 when choosing -m 1. The idea is the same: in a merge commit, the first parent is the branch you were on (normally main) and the second is the one you brought in.

Compare it with the --graph from the previous section: 4e8b2c9 and 2c6e9a4 have disappeared, which were the commits inside the merged branch. What is left is main's history at the level of integrations: each line is either a direct commit or "a whole feature came in here".

It is the right view for:

• Drafting a version's release notes.
• Answering "what has gone into main this week?".
• Counting how many features were integrated in a period.

This option is little known and very useful. It shows only the commits that have a reference pointing at them (a branch, a tag or HEAD), plus the minimum needed to keep the graph connected.

Four hundred commits reduced to five lines: the project's skeleton. It is the first thing worth running when you arrive at an unfamiliar repository, because in ten seconds it gives you the map: which versions exist, which branches are alive and where they were born.

Useful combinations:

Two complementary, straightforward filters:

--no-merges is especially important for statistics: if you count commits per author without it, whoever merges most looks like the most productive person.

From lesson 02-06 we remember A..B: "the commits reachable from B but not from A". It is asymmetric and answers "what is A missing from B?".

The triple dot A...B is the symmetric difference: the commits that are in one or the other, but not in both. It answers "how have these two branches diverged?".

With a plain A...B you cannot tell which commit is on which side. That is what --left-right is for:

It is the perfect view before merging or rebasing: at a glance you see how far each side has moved. And with the remote:

Two commits ahead on main, two on the branch. That rev-list --count is, incidentally, what lies behind the [ahead 2, behind 2] of git status and git branch -vv.

A useful addition: --cherry-mark marks with = the commits that are equivalent to one on the other side (same change, different hash) — what we saw with git cherry in lesson 05-03:

In lesson 02-06 we saw the basic --pretty=format: placeholders. Now we come to the two groups that turn a readable output into an excellent one: colours and alignment.

%C(auto) is the one to use by default, and there is a specific reason: applied to %d (the decorations), it paints each reference in its canonical colour — HEAD in cyan, local branches in green, remote ones in red, tags in yellow — exactly as git log --decorate does without a custom format. Writing that by hand is impossible.

On top of that, %C(auto) respects the color.ui configuration: if you redirect the output to a file or to grep, the escape codes are not emitted and the file stays clean.

When the format has several columns, without alignment it is a visual disaster. The padding placeholders solve it:

The complete format the team uses:

Breaking it down piece by piece:

• %C(auto)%h → abbreviated hash, with Git's standard colour for hashes.
• %C(blue)%<(16,trunc)%an%C(reset) → author in blue, exactly 16 columns, truncated if it does not fit.
• %C(green)%<(12)%ar%C(reset) → relative date ("2 days ago") in green, 12 columns.
• %C(auto)%d%C(reset) → the decorations, each in its canonical colour.
• %s → the subject, taking up the rest.

The result is tabular, readable and compact. In section 11 we shall turn it into an alias.

A reminder of the most-used placeholders, so you do not have to go back to lesson 02-06:

And so as not to repeat the format every time, it can be saved by name in the configuration:

git shortlog groups the commits by author. With no arguments it lists the messages grouped; with -s (summary) and -n (numbered), it gives the sorted count:

Useful options:

That last output is, literally, a draft set of release notes.

Two important warnings, because shortlog is easily misread:

• The number of commits does not measure productivity. A commit can be a comma or a whole feature. As a performance metric it is worse than useless: it is perverse, because it rewards artificial slicing.
• The same person can show up several times if they have used different names or emails (personal laptop, server, web platform). This is unified with a .mailmap file at the root of the repository:

Git applies it automatically in shortlog, log and blame.

Everything above combines, and that is where the real power lies. Some examples that answer specific day-to-day questions about task-manager:

--ancestry-path restricts the range to the commits that are on the path between the two ends, which is exactly what you want for answering "how did that commit get into main?".

And a comparison of the three views of the history we have seen, to have them together:

Having got this far, the problem is obvious: none of these commands gets typed by hand twice.

A Git alias is a short name for a long command. It is defined with git config:

From then on, git st is git status. Git resolves the alias before running and passes it the extra arguments:

Where they live. In the .gitconfig corresponding to the level you choose (lesson 01-05), under the [alias] section:

They can be edited by hand in the file — which is more convenient for the long ones — or with git config. And queried:

The three levels work exactly as for the rest of the configuration: --system, --global and local. Personal aliases go in --global; an alias specific to a project, in the local one. And remember that configuration is not cloned: the aliases are yours, not the repository's.

Two rules that avoid surprises:

• An alias cannot override an existing command. If you define alias.status, Git will ignore the alias and run the real command. It is a deliberate protection.
• Aliases can be chained, but with care: an alias that invokes another one works, and a recursive alias hangs Git.

An ordinary alias can only start with a Git subcommand. For everything else — chaining commands, using pipes, invoking external programs, placing the arguments somewhere other than at the end — you prefix !, which tells Git: "this is a shell command, run it as it is".

Three fundamental things about aliases with !:

This is the main risk and the number-one source of surprises. Git does a cd to the root of the working tree before running the alias. So if you are in ~/projects/task-manager/components/ and you run an alias with !ls, you will see the content of ~/projects/task-manager/, not that of the directory you are in.

Git provides a variable to mitigate it:

GIT_PREFIX contains the path relative to the root of the directory you were in when you invoked the alias (empty if you were already at the root). Any alias with ! that works with relative paths must take it into account:

Git sticks the arguments you type at the end of the alias's command. That is a problem when you need them in the middle:

In this case it works by coincidence. But if the argument goes in the middle, it does not:

The canonical solution is to define a shell function and call it:

The pattern '!f() { ...; }; f' reads like this: define a function called f, and then invoke it. The arguments Git sticks on the end become f's arguments. It is the standard idiom and you will see it in every .gitconfig in the world.

Use "$@" to pass all the arguments and "$1", "$2" for specific positions. And always quote them: without quotes, a branch name with odd characters breaks the alias.

Git uses /bin/sh. On many systems that is dash, not bash, and the bash extensions ([[ ]], arrays, mapfile) do not work. Write aliases in POSIX shell or invoke the interpreter explicitly:

For anything longer than three lines, the right answer is not an alias but a script on the PATH. Git has a lovely convention for that: any executable called git-<something> that is on the PATH can be invoked as git <something>:

Without configuring anything. It is the right route for complex logic, and as a bonus the script can be version-controlled and shared.

These are the ones that genuinely earn their place. Starting with the absolute classic:

lg is probably the most copied alias in the history of Git, and with good reason: it replaces a 180-character command that nobody remembers.

The complete table of the recommended set:

That last one is more useful than it looks: after six months nobody remembers all their aliases.

To install them in one go, it is more convenient to edit the file than to fire off twenty git configs:

Note the escaping: in the file, values with quotes or backslashes go inside double quotes and with the backslashes doubled. It is the most annoying part of aliases with !, and the reason it is worth testing them right after writing them.

And this connects with the earlier modules: aliases are not just for log. pending uses @{u} from lesson 04-06; amend is the --amend from 02-04; cleanup is the branch management from 03-06; praise is the blame from 06-03. An alias is the way of fixing into one gesture what you have learned to do properly, so that you do not have to remember the seven options every time.

Risk 1: the directory it runs from. Already seen: aliases with ! run from the root of the repository. Use GIT_PREFIX if the alias works with paths.

Risk 2: destructive aliases with short names. A git p that does push --force is an accident waiting to happen. Rule: the more destructive, the longer the name. And in the case of push --force, always use --force-with-lease (lesson 04-05).

Risk 3: dependence on your machine. Your aliases are not on the laptop of the colleague you ask for help, nor on the server. It is worth knowing the real command behind each one.

Risk 4: sh is not bash. The bash extensions fail silently or with odd errors.

Risk 5: aliases that hide effects. A git sync that does fetch + rebase + push is fine until the day there are conflicts and you cannot work out where the process has stopped.

Good practice:

• Let the name say what it does. pending is better than p.
• Version-control your .gitconfig. Many people keep their dotfiles in a repository of their own: aliases are valuable configuration and recreating them is a chore.
• Add aliases little by little. When you notice you are typing the same thing for the third time, there you have a candidate. Copying a list of forty aliases off the internet guarantees you will use none of them.
• Test the alias as soon as you create it, especially the ones with ! and quotes.
• For complex logic, git-<name> on the PATH, not a three-line alias.

Mistake 1: --graph without --oneline. The graph with full messages is unreadable. They always go together.

Mistake 2: forgetting --all and believing the branch does not exist. git log --graph only shows the current branch. Without --all, you do not see the others.

Mistake 3: confusing .. with .... A..B is asymmetric ("what A is missing"); A...B is symmetric ("how they have diverged"). With --left-right the ambiguity disappears.

Mistake 4: counting commits with shortlog without --no-merges. Whoever integrates most looks like the one who produces most.

Mistake 5: using the commit count as a performance metric. It is a bad metric and it creates perverse incentives.

Mistake 6: an alias with ! that assumes the current directory. It runs from the root. GIT_PREFIX.

Mistake 7: arguments in the middle of an alias without using a function. Git sticks them at the end. The pattern '!f() { ...; }; f' is the solution.

Mistake 8: badly done escaping in the .gitconfig. Double quotes around the value and doubled backslashes. Test the alias immediately.

Tip 1: %C(auto) by default in your formats. It colours the decorations correctly and respects both the configuration and redirections.

Tip 2: save formats by name. git config --global pretty.table '...' and then git log --pretty=table.

Tip 3: --simplify-by-decoration when you arrive at a new repository. Ten seconds for the complete map.

Tip 4: git rev-list --count A...B for the pure count. When you only want to know how much, not what.

Tip 5: a .mailmap as soon as somebody shows up duplicated. It is a three-line file that fixes shortlog, log and blame all at once.

Create a repository with this topology: four commits on main, a feature/a branch with two commits merged with --no-ff, a feature/b branch with two commits not merged, and a v1.0 tag on main's second commit. Then:

1. Show the complete graph with --graph --oneline --decorate --all.
2. Show only the mainline with --first-parent.
3. Show only the milestones with --simplify-by-decoration --all.
4. Show only the merges, and then only the commits that are not merges.
5. Explain which commits disappear in each view and why.

On the same repository:

1. Add two more commits to main and two more to feature/b.
2. Use main..feature/b and feature/b..main, and explain the difference.
3. Use main...feature/b with --left-right and identify each side.
4. Get the count with git rev-list --left-right --count.
5. Create a --pretty format with colours and alignment that shows hash, author (14 truncated columns), short date and subject.

1. Create the lg, who, pending and praise aliases from the table in section 11.
2. Create a history alias that accepts two arguments (function and file) and runs git log -L. Test it.
3. Create an alias that demonstrates the GIT_PREFIX problem: one that just runs ls, and another that does it properly. Run them from a subdirectory and compare.
4. List all your aliases with an alias.

Solution 1:

2a8c6f9 and 7d3e1b5 have disappeared: they are the commits inside feature/a, which are only reached through the merge's second parent.

Only the commits with a reference and the minimum needed to connect them: the skeleton.

Solution 2:

What the branch has and main does not: what would come in on merging.

What the branch is missing from main: what it would bring in on rebasing or merging main into it.

Solution 3:

The alias with arguments:

The GIT_PREFIX problem:

It has listed the root of the repository, not the directory we are in.

With GIT_PREFIX, the alias respects the directory it was invoked from.

This lesson has turned git log from a listing into a querying tool, and has removed the friction of using it. The essentials:

• --graph --oneline --decorate --all is the canonical view of the topology. All four go together.
• --first-parent gives main's history at the level of integrations, without the insides of the merged branches. It is the same "first parent" as revert's -m 1 and bisect --first-parent.
• --simplify-by-decoration reduces the history to its milestones: the first thing to run in an unfamiliar repository.
• --merges / --no-merges separate integrations from real work; --no-merges is all but mandatory in any statistic.
• A...B with --left-right answers "how have these two branches diverged?", with < and > marking each side. git rev-list --left-right --count gives just the count.
• --pretty=format: with %C(auto) and the alignment placeholders %<(N,trunc) produces tabular, coloured output; save them by name in pretty.<name>.
• git shortlog -sn --no-merges summarises the contributions, with .mailmap to unify identities — and with the warning that counting commits measures nothing useful.
• Aliases live in the [alias] section of the .gitconfig at whichever level you choose. The simple ones are a name for a subcommand; the ones starting with ! are shell, with three cautions: they run from the root (use GIT_PREFIX), the arguments are stuck on the end (use the pattern '!f() { ...; }; f') and they run under sh, not bash.
• For long logic, an executable git-<name> on the PATH is better than an alias.
• And the underlying idea: an alias fixes into one gesture what you have learned to do properly. praise, pending, milestones or cleanup are the previous lessons condensed into a single word.

The team now knows how to interrogate its history comfortably. But task-manager is about to stop being a single repository: the buttons, dialogs and form fields that Ana has gradually been extracting have turned into an internal library, ui-components, which lives at git.example.com/team/ui-components.git and which two other company projects also want to use.

The question is how a project is composed out of several repositories without copying and pasting code, and without losing the traceability of which version of the library each version of the application uses. Git's native answer is submodules, and that is lesson 06-05: Git Submodules.