Metadata-Version: 2.4
Name: bsk-git-viewer
Version: 0.1.0
Summary: Interactive local Git history and command inference viewer
Author: Bhupender Singh
License-Expression: MIT
Project-URL: Homepage, https://github.com/bhupender2403/bsk_git_viewer
Project-URL: Repository, https://github.com/bhupender2403/bsk_git_viewer
Project-URL: Issues, https://github.com/bhupender2403/bsk_git_viewer/issues
Keywords: git,visualization,commit-graph,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: dulwich
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# 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](https://pipx.pypa.io/stable/):

```bash
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:

```bash
python -m pip install bsk-git-viewer
```

### Install from source

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

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

For development dependencies:

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

Install frontend dependencies:

```bash
npm --prefix frontend install
```

## Usage

Open a repository with one command:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Load its repository data through the debug command:

```bash
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:

```bash
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`:

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

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

```bash
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

```text
GET /api/health
```

### Repository graph

```text
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:

```bash
pytest
```

Build the frontend:

```bash
npm --prefix frontend run build
```

Lint the frontend:

```bash
npm --prefix frontend run lint
```

## Project structure

```text
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](LICENSE).
