Documentation

Everything you need to explore a repository with git-tm, from the first run to time travel.

Install

git-tm needs Node.js 18.3 or newer and git on your PATH. It has no other dependencies.

npm install -g git-tm

Or try it once without installing:

npx git-tm

Usage

Run it inside any repository, or any folder within one:

git tm

Then open http://localhost:7890, or add --open to open your browser automatically. The server keeps running until you press Ctrl+C.

As a Git subcommand

Git runs any program named git-<name> on your PATH as git <name>. npm installs the program as git-tm, so git tm and git-tm are the same thing. These all work:

git tm
git tm ../other-repo
git -C ../other-repo tm
git-tm --open

Use git tm -h for help. Git handles git tm --help itself and looks for a manual page instead.

Options

OptionDescription
[path]Repository to open. Defaults to the current folder; any subfolder of a repository works.
-p, --port <n>Port to listen on. Default 7890; if it is busy, the next free port is used.
--host <address>Interface to bind. Default 127.0.0.1, so only your machine can connect.
-o, --openOpen the browser once the server is running.
--no-avatarsDo not load author pictures from GitHub or Gravatar; initials are shown instead.
-v, --versionPrint the version.
-h, --helpPrint help.

History

The History view lists commits newest first with a graph of branch lanes and merges. Badges show the current branch, other local branches, remote branches and tags. Merge commits are drawn as hollow dots, and HEAD has a ring.

Commits and diffs

Click a commit to open its details next to the list: the full message, author and committer, parents, and every branch and tag that contains it. If the repository has a GitHub, GitLab or Bitbucket remote, a button opens the commit there.

Browse and blame

The Files tab of a commit shows the repository exactly as it was at that commit. Open any folder or file; for a file, Blame shows which commit last changed each line, and History lists every commit that touched it, following renames.

A file viewed at an older commit with blame next to each line
A file at an earlier commit, with blame.

Time travel

The Compare view answers one question: what happens if I move from this point in history to that one? Pick a From and a To. Each can be a commit, branch, tag or, for To, your working tree. Type a name or short commit id, or use the picker button to search.

Directions

DirectionWhenWhat you see
Forward in timeTo contains FromThe commits applied on the way, and how much later To is.
Back in timeFrom contains ToThe commits undone on the way back.
Across branchesThey divergedThe commits undone back to the common ancestor, then the commits applied to reach To.

The ⇄ button reverses the trip.

Stepping through the journey

The slider walks through the snapshots between From and To, one commit at a time: back along From's first parents to the common ancestor, then forward along To's. At each step the file list shows what has changed so far. Use the arrow buttons, the arrow keys, or click a commit in the Applied or Undone list to jump to it. The current step is kept in the URL, so you can share or reload it.

Compare view stepped back to step 4 of 6 between two commits
Stepping through a forward journey. The highlighted commit is the current step.

Picking commits from History

History in time travel mode with From and To selected and the travel bar at the bottom
Time travel mode: the bar at the bottom shows your From and To.

Direct or since branch point

Direct (a..b in the URL) shows everything that differs between the two snapshots. Since branch point (a...b) shows only what To added after the two diverged, the way a pull request does.

Press / to focus the search box. Plain words search commit messages; prefixes narrow the search:

QueryFinds
fix loginCommits whose message contains the text (case-insensitive)
author:adaCommits by an author, matching name or email
path:src/app.jsCommits that touched a file or folder (a file's History button also follows renames)
code:parseConfigCommits that added or removed a string (git log -S)
a1b2c3dJumps straight to a commit

Prefixes can be combined, for example author:ada path:src. Use quotes for spaces: author:"Ada Lovelace". Each active filter appears as a chip above the list; press Esc to clear.

Insights

Insights summarises the history of all branches, or of the branch selected in the sidebar: total commits, contributors, branches and tags, an activity heatmap for the past year, the weekly rhythm by day and hour, and the top contributors. Click a contributor to see their commits. Merge commits are left out, and .mailmap is respected.

Insights with commit totals, an activity heatmap, contributors and weekly rhythm

Keyboard shortcuts

KeysAction
j k or ↓ ↑Next / previous commit
EnterOpen the selected commit (or pick it in time travel mode)
tTime travel mode: pick From, then To
Shift + clickTravel from the open commit to the clicked one
← →Step through a journey in Compare
/Search
EscLeave time travel mode, close the commit, or clear the search
g then h / c / iGo to History / Compare / Insights
?Show all shortcuts

Privacy and safety

Troubleshooting

“Your browser blocked this request”

An ad blocker or privacy extension cancelled one of git-tm's requests to localhost. git-tm avoids the URL patterns these filter lists are known to block, but if it happens, allow localhost in the extension and reload.

“Lost connection to git-tm”

The git-tm process stopped, for example because its terminal was closed or Ctrl+C was pressed. Start it again; the page reconnects by itself.

Port already in use

git-tm moves to the next free port and prints the address it chose. Use -p to pick one yourself.

“No manual entry for git-tm”

That is Git answering git tm --help. Use git tm -h or git-tm --help.

“Not a git repository”

Run git-tm inside a repository or pass its path: git tm path/to/repo.

How it works

git-tm starts a small HTTP server built only on Node's standard library. It asks git for machine-readable output (for example git log --format=…, git diff --raw -z, git blame --porcelain), so it supports everything your installed git does: worktrees, submodules, SHA-256 repositories and .mailmap. The interface is plain HTML, CSS and JavaScript modules, with no framework and no build step.

src/
  cli.js           # command-line entry point
  server.js        # HTTP server and JSON API
  git.js           # git commands and output parsing
  public/          # the web interface
test/              # node:test suites
docs/              # this website

Contributing

Issues and pull requests are welcome on GitHub. There is nothing to install or build:

git clone https://github.com/nandhu-44/Git-Time-Machine.git
cd Git-Time-Machine
node src/cli.js .

Run the tests with npm test. Releases are published to npm from GitHub Actions when a version tag is pushed (npm version patch, then git push origin main --follow-tags).

This website lives in the docs/ folder and is served by GitHub Pages.