BSK Git Viewer

BSK Git Viewer is a local, read-only Git history visualizer. It reads repository objects, refs, and the local HEAD reflog, exposes the resulting graph through a FastAPI backend, and renders an interactive commit timeline, branch graph, and command-inference pane in React.

The project is intended to help people learn how Git history is structured and to make complicated branch and merge histories easier to inspect.

Features

• Reads local Git repositories without changing them.
• Displays commits reachable from local branch heads.
• Renders parent-child relationships, including merge commits.
• Assigns separate graph lanes to additional merge parents.
• Shows local branch names at their current head commits.
• Prominently marks the currently checked-out HEAD commit and branch.
• Provides a compact overview containing every displayed commit.
• Highlights the part of the graph currently visible in the lower pane.
• Supports click navigation from the overview.
• Supports horizontal scrolling and click-drag panning in the branch graph.
• Shows commit message, author, timestamp, and short SHA when hovering over a commit in the branch graph.
• Shows compact inferred Git commands and confidence for commits in the visible graph region, with expandable evidence and details.
• Infers common commit, merge, branch, switch, cherry-pick, and rebase workflows using graph structure, tree diffs, refs, and reflog evidence.
• Includes a scenario runner for generating test repositories and Git histories.

Requirements

• Python 3.10 or newer
• Git command-line tools
• Node.js and npm for frontend development

Installation

Install from PyPI

After the package is published, the recommended installation for this command-line application will be through pipx:

pipx install bsk-git-viewer

pipx keeps the application and its dependencies in an isolated environment while making the bsk-git-viewer command available globally.

Installation with standard pip will also be supported:

python -m pip install bsk-git-viewer

Install from source

Until the first PyPI release, clone the repository and install the Python package locally:

git clone https://github.com/bhupender2403/bsk_git_viewer.git
cd bsk_git_viewer
python -m pip install -e .

For development dependencies:

python -m pip install -e ".[dev]"

Install frontend dependencies:

npm --prefix frontend install

Usage

Open a repository with one command:

bsk-git-viewer /path/to/repository

The command validates the repository, starts the local viewer, and opens it in the default browser. Available options include:

bsk-git-viewer . --port 8000
bsk-git-viewer . --no-browser
bsk-git-viewer . --host 127.0.0.1

The repository path can be absolute or . for the current directory.

Running from source

Start the backend and provide the root of a local Git repository:

bsk-git-viewer --repo-path /path/to/repository --port 8000

The backend listens on http://127.0.0.1:8000.

In another terminal, start the frontend:

npm --prefix frontend run dev

Open http://localhost:5173 in a browser.

The selected path must be the repository root and must contain a .git directory.

Using the graph

• The Commit history lane is an overview of all displayed commits.
• The highlighted area in the overview represents the visible portion of the Commit Graph pane.
• Click the overview to move the lower graph to that location.
• Use the left and right arrow keys while the overview is focused to navigate.
• Scroll horizontally in the Commit Graph or hold the primary mouse button and drag to pan.
• Hover over a graph commit to see its details.
• Branch labels are displayed beside the commits referenced by local branch heads.
• The checked-out commit has an accent halo and a HEAD · branch-name badge.
• The Inferred commands pane follows the currently visible graph region. Each compact row shows a command and confidence percentage; expand it to see the command type, commit, confidence bar, and supporting reason.

Command inference

Inference is evidence-based and intentionally reports a confidence rather than claiming that Git history records every command exactly:

• Root and ordinary commits suggest git init and git commit.
• Multi-parent commits suggest git merge.
• Equivalent patches on non-ancestral branches suggest git cherry-pick.
• Ordered sequences of equivalent patches suggest git rebase.
• HEAD reflog replay steps combined with tree diffs distinguish conflict resolution with git rebase --continue from omitted patches with git rebase --skip. These workflows include the initiating git rebase command in the inferred command list.
• A branch's first observed HEAD checkout suggests both git branch <name> and the equivalent git switch -c <name>. Later confirmed checkouts suggest git switch <name>.

Confidence is higher when tree-diff or reflog evidence supports a command and lower when only the current repository state is available. For example, a root commit does not prove whether the repository was initialized locally or cloned.

Generating a merge test repository

bsk-git-debug gitrun executes a line-based Git scenario. It waits for a random one to two seconds between commands so generated commits receive useful, separated timestamps.

The included scenario creates several branches and genuine two-parent merge commits:

bsk-git-debug gitrun \
  /tmp/bsk-merge-test \
  docs/scenarios/multi_branch_merge.txt

The target directory must not already exist.

Inspect the generated repository:

git -C /tmp/bsk-merge-test log --all --graph --decorate --oneline

Load its repository data through the debug command:

bsk-git-debug readrep /tmp/bsk-merge-test

The cherry-pick scenario creates a feature commit, advances main independently, and cherry-picks the feature tip:

bsk-git-debug gitrun \
  /tmp/bsk-cherry-pick-test \
  docs/scenarios/cherry_pick.txt

The rebase scenario preserves the original feature history on a backup branch, then replays two feature commits onto an independently advanced main:

bsk-git-debug gitrun \
  /tmp/bsk-rebase-test \
  docs/scenarios/rebase.txt

Conflict-resolution scenarios exercise both ways to resume a stopped rebase:

bsk-git-debug gitrun \
  /tmp/bsk-rebase-continue-test \
  docs/scenarios/rebase_continue.txt

bsk-git-debug gitrun \
  /tmp/bsk-rebase-skip-test \
  docs/scenarios/rebase_skip.txt

The scenario language supports repository initialization, file operations, staging and commits, branch creation and checkout, merges, cherry-picks, rebases (including continue, skip, and abort), resets, tags, status, and log inspection. See the supported-command list in src/bsk_git_viewer/gitcreate/git_sceneria_creator.py.

API

Health check

GET /api/health

Repository graph

GET /api/repository

The repository response includes:

• Repository and .git paths
• Commits with parents, timestamps, assigned branch, and graph lane
• Displayed branch list
• Local branch names and their exact head commit IDs
• The checked-out HEAD commit ID and current branch name
• Inferred commands with their commit ID, type, confidence, and supporting reason

Development

Run the Python test suite:

pytest

Build the frontend:

npm --prefix frontend run build

Lint the frontend:

npm --prefix frontend run lint

Project structure

src/bsk_git_viewer/
  command_inference/
                Inference orchestration and per-command rules
  git/          Git object, tree, and diff handling
  gitcreate/    Test repository scenario runner
  inference/    Patch similarity and pre-diff computation
  loader/       Repository and reflog loading
  server.py     FastAPI application
  cli.py        Viewer command-line entry point

frontend/src/
  api/          Backend API client
  components/   Timeline, branch graph, and inferred-command UI
  pages/        Repository page composition
  types/git.ts  API data types
  utils/        Color and time formatting helpers

Current limitations

• The checked-out branch is used as the primary graph lane. For detached HEAD, a containing local branch is preferred, followed by the first local branch; repositories without local branches use a synthetic HEAD lane.
• The repository path must contain a regular .git directory; bare repositories and linked worktrees are not yet supported.
• Remote-tracking branches and tags are not displayed.
• Very large repositories can take time to analyze and produce wide graphs.
• Git command inference is experimental and currently covers root, ordinary commit, merge, branch creation/switching, cherry-pick, rebase, and rebase continue/skip commands.
• Commit history usually cannot prove the exact command spelling used; inferred alternatives and confidence values reflect that ambiguity.
• Cherry-pick inference compares single-parent tree diffs across non-ancestral branches and may not identify heavily conflict-resolved cherry-picks.
• Rebase inference requires at least two ordered patch-equivalent commits and requires the original commits to remain reachable from a local branch.
• Rebase continue/skip inference combines the local HEAD reflog with tree diffs, so it is unavailable when the reflog or original commits have been removed.
• Branch creation and switch inference depends on local HEAD reflog entries; repositories whose reflogs have expired retain only lower-confidence branch-head inference.
• The viewer diagnoses and visualizes repository history but does not modify or repair it.

License

This project is available under the MIT License. See LICENSE.