snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

docs/git/reading-history.md

@@ -0,0 +1,88 @@
+# Reading history
+
+One of the things that makes Git so valuable is its facilities for
+studying history -- both
+
+- very recent history (e.g., rereading your own branch before you
+  send a PR), and
+- the distant past (e.g., tracking down when and why some piece
+  of code became the way it is.)
+
+This guide, written by Greg Price, will help you take advantage of
+these powerful abilities.
+
+## Use a graphical client
+
+One great way to read history: [use a graphical Git client](setup.md#get-a-graphical-client)!
+Especially helpful for
+
+- reading through the recent commits, or
+- clarifying how branches are related to each other.
+
+## The "secret" to using `git log -p`
+
+Use `git log -p`, with this important secret:
+
+- In the pager that `git log` puts you into, hit `/` to search, then enter
+  the pattern `^c` -- that is, caret, then `c`. Then hit `n`/`N` for
+  next/previous match.
+
+- This finds lines that begin with `c`. Because of thoughtful design in
+  the default format of `git log`, these are exactly the first line of the
+  log entry for each commit. So with this search pattern, you effectively
+  get **keybindings for "next/previous commit"**. This makes a huge
+  difference in skimming quickly past boring commits without missing
+  anything.
+
+- For a further upgrade, use `git log --stat -p` (you might alias this as
+  e.g., `git lsp`.) Now every time you hit `n` or `N`, you see the commit
+  message and complete list of affected files for the new commit -- a good
+  summary to help decide whether to read in more detail or hit `n`/`N`
+  again to move on.
+
+## Filter `git log` down to relevant commits
+
+Use some of `git log`'s many features to filter down to commits you
+care about. For example:
+
+- Filter to a range of commits with `git log A..B`. E.g., to reread your
+  current branch relative to upstream main, you might say
+  `git log --stat -p upstream/main..`, or `git log --stat -p @{u}..`.
+  (Greg has the latter aliased as `git usp`, and types it constantly.)
+
+- Filter to changes touching certain files or directories:
+  `git log PATHS`.
+
+- Filter to changes touching lines that mention some pattern:
+  `git log -G PATTERN`.
+
+- Filter to changes adding or removing mentions of some pattern:
+  `git log -S PATTERN`. This feature is traditionally called the
+  "pickaxe", presumably in honor of its power to mine just the right bit
+  of historical/explanatory gold.
+
+- Many more. Do take a few minutes to skim through the documentation in
+  `git help log` (or [this web version](https://git-scm.com/docs/git-log))
+  to get an idea of what's available; and perhaps an hour now and then to
+  read and try things in more detail.
+
+## Filter in your graphical client
+
+Try all those `git log` filtering features in your graphical client -- it
+may even support the very same command-line options to do it. For
+example, `gitk upstream/main..` shows basically the same information as
+`git log --stat -p upstream/main..`, but graphically.
+
+## Git a summary, with `git log --oneline`
+
+Try `git log --graph --oneline --decorate --boundary`. (Quite a mouthful;
+Greg has this aliased as `git k`, in homage to `gitk`.) It can be a
+lightweight alternative to your graphical client for simple, routine
+situations, giving a compact list of commits each on just one line.
+
+- To list the commits local to your current branch: `git k @{u}..`.
+  (Greg has an alias for this, and types it constantly.)
+
+- To list all your own local commits on all branches:
+  `git k --branches @ --not --remotes=origin --remotes=upstream`.
+  (For explanation, see `git help log`.)