Gitlib is a local-first tool for managing Git repositories stored under ~/git. It scans your local repos, tracks detected technologies, and lets you store notes for each project without depending on GitHub.

On first run, Gitlib bootstraps its local app data in ~/.git-library/.

Run it directly from the repository:

python3 -m gitlib list
python3 -m gitlib tui

Or install it in editable mode and use the gitlib command:

pip install -e .
gitlib list
gitlib tui

Operational notes:

• First run creates ~/.git-library/ for config and SQLite data.
• The default scan root is ~/git.

These commands are implemented today:

gitlib list [--tech TAG] [--notes-only] [--json]
gitlib show <repo> [--json]
gitlib scan
gitlib open code <repo>
gitlib open remote <repo>
gitlib tui
gitlib notes edit <repo>

Command summary:

• gitlib list lists all discovered repos.
• gitlib list --tech TAG filters repos by a detected technology tag.
• gitlib list --notes-only shows only repos with notes.
• gitlib list --json returns machine-readable output.
• gitlib show <repo> shows details for one repo.
• gitlib scan refreshes repo discovery and technology metadata.
• gitlib open code <repo> opens the repo root in a new VS Code window.
• gitlib open remote <repo> opens the preferred configured remote in your browser.
• gitlib tui launches the interactive terminal UI.
• gitlib notes edit <repo> opens your configured editor to update repo notes.

Launch the full-screen terminal UI with:

gitlib tui

The TUI mirrors the current CLI capabilities:

• Repo list
• Repo detail view
• Compact notes editor
• Scrollable rendered README.md preview from the repo root
• Remote landing-page links for configured remotes
• Refresh scan
• Note editing

Keybindings:

• q and Ctrl+C quit the TUI
• r refreshes repo data and runs a scan
• / focuses search
• e enters notes edit mode
• v opens the selected repo in VS Code
• o opens the preferred remote landing page in your browser
• Ctrl+S saves notes
• Esc cancels note editing or leaves the focused input

To scroll a long README.md, move focus into the README pane with Tab or click it with the mouse, then use the arrow keys or normal terminal scrolling keys.

Gitlib defaults to launching VS Code with:

vscode_command = ["code", "--new-window"]

You can change that in ~/.git-library/config.toml if you use another build, for example:

vscode_command = ["code-insiders", "--new-window"]

The default requires the code shell command to be installed and available on PATH.

Your ~/.git-library/config.toml needs:

roots = [
    "~/git",
]

vscode_command = [
    "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
    "--new-window",
]

ignore_dirs = [
    ".git",
    "node_modules",
    ".next",
    "dist",
    "build",
    "venv",
    "env",
    "obj",
    "bin",
    "lib",
    "include",
    ".pytest_cache",
      ]