# Installing And Running Githical

This document covers GitHub Release installation, local builds, safe
verification, and the expected V1 workflow.

## Prerequisites

- The system `git` binary available on `PATH`.
- A terminal that can run an interactive Bubble Tea application.

Githical shells out to the system `git` binary through narrow typed wrappers in
`internal/git`. It relies on Git for repository discovery, user configuration,
credentials, hooks, signing, remotes, and repository edge cases.

Go 1.26.5 or a compatible newer Go toolchain is required only when building from
source.

## Install From GitHub Releases

Install with Homebrew on macOS or Linux:

```sh
brew install essenciary/tap/githical
```

After `Essenciary.Githical` is accepted into the WinGet community repository,
install it on Windows with:

```powershell
winget install --id Essenciary.Githical --exact
```

You can also download the matching archive and `checksums.txt` from
`https://github.com/essenciary/githical/releases`.

Release assets are named:

- `githical_<version>_darwin_arm64.tar.gz`: macOS Apple Silicon.
- `githical_<version>_darwin_amd64.tar.gz`: macOS Intel.
- `githical_<version>_linux_arm64.tar.gz`: Linux ARM64.
- `githical_<version>_linux_amd64.tar.gz`: Linux x86_64.
- `githical_<version>_windows_arm64.zip`: Windows ARM64.
- `githical_<version>_windows_amd64.zip`: Windows x86_64.
- `githical_<version>_linux_arm64.deb`: Debian/Ubuntu ARM64 package.
- `githical_<version>_linux_amd64.deb`: Debian/Ubuntu x86_64 package.
- `githical_<version>_linux_arm64.rpm`: RPM-based Linux ARM64 package.
- `githical_<version>_linux_amd64.rpm`: RPM-based Linux x86_64 package.

Verify the downloaded archive before installing:

```sh
sha256sum -c checksums.txt --ignore-missing
```

On macOS, use:

```sh
shasum -a 256 -c checksums.txt --ignore-missing
```

Extract the archive and place the contained `githical` binary somewhere on
`PATH`, such as `/usr/local/bin` or `$HOME/bin`. Windows archives contain
`githical.exe`; place it in a directory included in `%PATH%`.

On Debian or Ubuntu, download the matching `.deb` and install it with:

```sh
sudo apt install ./githical_<version>_linux_amd64.deb
```

On Fedora or another DNF-based distribution, use the matching `.rpm`:

```sh
sudo dnf install ./githical_<version>_linux_amd64.rpm
```

The native Linux packages install Githical under `/usr/bin` and declare `git`
as a required dependency.

The Homebrew formula builds from the checksummed source release and declares
`git` as a dependency. The WinGet package installs the portable Windows archive
and declares `Git.Git` as a dependency.

Public GitHub release artifacts include build-provenance attestations. With the
GitHub CLI installed, verify a downloaded artifact with:

```sh
gh attestation verify githical_<version>_linux_amd64.tar.gz \
  --repo essenciary/githical
```

## Build From Source

From the repository root:

```sh
go build -o /tmp/githical ./cmd/githical
```

This writes the development binary to `/tmp/githical` and leaves the source
repository unchanged.

To build runnable local and release-ready distribution archives into the
repository's `dist/` directory:

```sh
./scripts/build-dist.sh
```

The script writes:

- `dist/githical`: the current machine's runnable binary.
- `dist/githical_<version>_darwin_arm64.tar.gz`: macOS Apple Silicon archive.
- `dist/githical_<version>_darwin_amd64.tar.gz`: macOS Intel archive.
- `dist/githical_<version>_linux_arm64.tar.gz`: Linux ARM64 archive.
- `dist/githical_<version>_linux_amd64.tar.gz`: Linux x86_64 archive.
- `dist/githical_<version>_windows_arm64.zip`: Windows ARM64 archive containing
  `githical.exe`.
- `dist/githical_<version>_windows_amd64.zip`: Windows x86_64 archive
  containing `githical.exe`.
- `dist/githical_<version>_source.tar.gz`: immutable source archive used by
  package managers.
- `dist/checksums.txt`: SHA-256 checksums for all release archives.

Install by extracting the matching archive, verifying it against
`dist/checksums.txt`, and running it from inside a Git repository. The target
host must also have the system `git` binary available on `PATH`.

## Run

Run Githical from inside the repository you want to inspect:

```sh
cd /path/to/your/repository
/tmp/githical
```

The app detects the repository from the current working directory by default.
You can also pass a path explicitly:

```sh
githical [PATH]
githical --repo PATH
githical --help
githical --version
```

Do not pass both positional `PATH` and `--repo PATH`. `--help` prints usage
without launching the TUI. `--version` prints the build version and exits;
unreleased local builds default to `dev`.

The default view is `Changes`. Use `tab` or the arrow keys to switch between
top-level views, and use `Ctrl+P` to open the command palette.

When built with `./scripts/build-dist.sh`, you can run the local binary from
this checkout:

```sh
./dist/githical
```

## Config

Githical reads an optional JSON config file from the OS config directory:
`<os.UserConfigDir()>/githical/config.json`. Missing config files are ignored
and are not created on startup. If the file exists but is not valid JSON,
Githical starts in an unavailable TUI state that shows the config path and the
parse error.

The config supports an external editor preference, Git executable, startup
theme selection, file-name styling, custom themes, and operational limits:

```json
{
  "editor": "code --wait",
  "git_binary": "git",
  "view": "system",
  "active_theme": "githical",
  "file_style": "rich",
  "limits": {
    "recent_history": 30,
    "journal_read": 2000,
    "journal_batch": 50,
    "reflog": 200,
    "patch_preview_lines": 5000
  }
}
```

`view` can be `light`, `dark`, or `system`. `system` is resolved once on
startup from the terminal background.

`active_theme` defaults to `githical`.

Built-in theme IDs:

- `githical`
- `dracula`
- `nord`
- `catppuccin`
- `tokyo-night`
- `gruvbox`
- `solarized`
- `one-dark`
- `monokai`
- `ayu`
- `github`

`file_style` can be `rich` or `muted`; `rich` is the default and adds semantic
color to file names, while `muted` preserves plain path styling.

`git_binary` defaults to `git`, resolved from `PATH`; set it to an executable
name or absolute path when Githical should use a specific Git install.

Startup theme mode, active theme, and theme style can also be changed from the
command palette. Githical writes those changes to `config.json`; theme and
theme mode changes show a restart required status because palettes are applied
on startup.

Custom themes can be added with a `themes` array. A user theme may replace a
built-in by using the same `id`.

Each custom theme has:

- `id`
- `name`
- `light`
- `dark`

Each `light` and `dark` variant defines these `#RRGGBB` colors:

- `ink`
- `subtle`
- `line`
- `accent`
- `accent_ink`
- `top_bar`
- `tab_bar`
- `footer`
- `panel`
- `added`
- `removed`
- `added_panel`
- `removed_panel`
- `warn`
- `code_keyword`
- `code_string`
- `footer_divider`

Example:

```json
{
  "active_theme": "custom",
  "themes": [
    {
      "id": "custom",
      "name": "Custom",
      "light": {
        "ink": "#1F2937",
        "subtle": "#6B7280",
        "line": "#D6DCE6",
        "accent": "#0369A1",
        "accent_ink": "#F0F9FF",
        "top_bar": "#E8EEF7",
        "tab_bar": "#F1F5F9",
        "footer": "#E5E7EB",
        "panel": "#FAFBFD",
        "added": "#047857",
        "removed": "#DC2626",
        "added_panel": "#DCFCE7",
        "removed_panel": "#FEE2E2",
        "warn": "#B45309",
        "code_keyword": "#1D4ED8",
        "code_string": "#047857",
        "footer_divider": "#94A3B8"
      },
      "dark": {
        "ink": "#E6E8EF",
        "subtle": "#9AA3B2",
        "line": "#303846",
        "accent": "#7DD3FC",
        "accent_ink": "#06131A",
        "top_bar": "#202634",
        "tab_bar": "#262C3A",
        "footer": "#1B202B",
        "panel": "#151922",
        "added": "#86EFAC",
        "removed": "#FCA5A5",
        "added_panel": "#123024",
        "removed_panel": "#3A2026",
        "warn": "#FDE68A",
        "code_keyword": "#93C5FD",
        "code_string": "#A7F3D0",
        "footer_divider": "#4A5365"
      }
    }
  ]
}
```

Omitted `limits` fields use defaults. Unknown config keys, malformed theme
objects, missing light or dark variants, duplicate user theme IDs, invalid
hex colors, and non-positive numeric limits stop startup with a config error.

Editor resolution order is:

1. `GITHICAL_EDITOR`
2. config `editor`
3. `VISUAL`
4. `EDITOR`

For tests and advanced manual troubleshooting, set
`GITHICAL_CONFIG=/path/to/config.json` to override the config file path.
Set `GITHICAL_ASCII=1` to use plain ASCII symbols on terminals that do not
render Unicode symbols well.

Githical also writes app-managed UI state to
`<os.UserConfigDir()>/githical/state.json`. This file currently stores
`main_pane_width`, the internal panel width after the panes are resized, so the
same split can be restored on the next startup. For tests and advanced manual
troubleshooting, set `GITHICAL_STATE=/path/to/state.json` to override the UI
state file path.

## Safe Verification

Use a temporary repository for a first run. Do not run the verification
repository inside a user project.

```sh
go build -o /tmp/githical ./cmd/githical

rm -rf /tmp/githical-demo
mkdir /tmp/githical-demo
cd /tmp/githical-demo

git init
git config user.email githical@example.test
git config user.name "Githical Demo"
printf 'hello\n' > README.md
git add README.md
git commit -m "Initial demo commit"

/tmp/githical
```

Inside the TUI, you can inspect the clean repository state, switch views, open
the command palette with `Ctrl+P`, and quit with `q`. To verify the `Changes`
view without affecting a user repository, edit `/tmp/githical-demo/README.md`
from another shell and refresh by restarting `/tmp/githical`.

## Expected Workflow

Githical is designed around a small set of persistent views:

- `Changes`: inspect changed, staged, unstaged, and untracked files; preview
  diffs; stage and unstage files; stage and unstage all; stage and unstage
  selected hunks or selected lines; discard a selected file after confirmation;
  open a selected file in `GITHICAL_EDITOR`, config `editor`, `VISUAL`, or
  `EDITOR`; write, reuse, commit, and amend commit messages; and see the
  `Will commit` summary.
- `History`: inspect recent commits, changed files, and commit patches; copy the
  selected hash; revert a selected commit after confirmation; and reset the last
  local commit while keeping changes.
- `Branches`: list local and remote branches; create a local branch without
  checking it out automatically; checkout local branches and remote-tracking
  branches with guardrails; undo the last Githical checkout when safe; delete
  local branches with merged and unmerged safety checks; delete remote branches
  after confirmation; merge local `main` into the current branch; rebase the
  current branch onto local `main`; undo the last completed Githical merge or
  rebase when Git state still matches; and continue or abort an in-progress
  rebase.
- `Sync`: list remotes and tracking metadata; show ahead and behind counts;
  fetch; perform a guarded fast-forward pull; rebase local commits during a
  guarded diverged pull; perform a guarded normal push; and perform a guarded
  force push.
- `Stash`: create, list, inspect, apply, pop, and delete stashes with guarded
  destructive actions.
- `Journal`: view recent append-only operation journal entries, filter them,
  refresh them, inspect the journal path, see recent reflog recovery points, and
  recover HEAD to a selected reflog point while keeping working-tree changes.

Mutating workflows are guarded with plain-language confirmations where the
operation can discard work, rewrite history, leave changes out of a commit, or
change repository state in a surprising way.

## Intentionally Unimplemented

These items are visible as current V1 gaps and should not be documented as
available:

- Automatic merge pulls for diverged branches.
- Full pull/rebase auto-stash controls beyond the current guarded pull behavior.

## Project Links

- License: MIT, documented in `LICENSE`.
- Contributions: `CONTRIBUTING.md`.
- Security reporting: `SECURITY.md`.
- Releases: `https://github.com/essenciary/githical/releases`.