Git Integration

Philosophy

Hook collections are plain JSON files stored on disk. Git integration lets you version-control these files directly from within Hook, without switching to a terminal or external Git client.

Every save can optionally be staged and committed automatically, creating a full history of collection changes. Push and pull let you share collections with a team via a remote repository.

Enabling Git

Git integration requires libgit2. Hook is compiled with -DHAVE_LIBGIT2 and linked against -lgit2.

Enable Git in the Git popup (click Git on the toolbar):

1. Check “Enable Git integration”.
2. Set Author name and Email.
3. Fill in Remote settings (see below).
4. Click “Save settings”.

On save, if no .git directory exists, Hook initializes a new repository in the current working directory.

Watched directories

Git operations (Stage All, status) only apply to files in:

• collections/
• environments/
• mock-routes/
• scripts/
• user-agents/

Files outside these directories are ignored by Hook’s Git panel.

Git panel (GUI)

The Git popup shows:

Top section

• Enable Git integration checkbox
• Author / Email fields
• Branch label (current branch)

Buttons row 1 (global operations)

• Refresh: update status and log
• Stage All: stage all changed files in watched directories
• Push: push current branch to origin
• Pull: fetch from origin and fast-forward merge

Buttons row 2 (per-file operations)

These operate on the selected file in the Status list:

• Stage: stage the selected file
• Unstage: unstage the selected file
• Reset File: restore the selected file from the last commit (shows confirmation dialog)
• Reset Dir: restore all files in the same directory as the selected file (shows confirmation dialog)
• Reset All: restore all watched files from the last commit (shows confirmation dialog)

Status list

Shows changed files with status flags: [staged], [new], [modified], [deleted]. Click a file to select it for per-file operations.

Commit section

Enter a commit message and click Commit. If no files are staged, the commit is rejected with a log message.

Log section

Shows recent commit history (hash + message).

Branch section

Enter a branch name, then Create or Switch.

Remote settings

• Repo URL: remote repository URL (HTTPS or SSH)
• Branch: target branch name
• Auth type: None, Token, Basic, or SSH
  • Token: personal access token (used as password with x-access-token user)
  • Basic: username + password
  • SSH: path to private key file (public key derived as <path>.pub)
• Save settings: saves all git settings to hook.conf

Push and Pull

Push sends the current branch to the “origin” remote. The remote URL and auth credentials must be configured in Remote settings.

Pull fetches from “origin” and fast-forward merges the current branch. If the merge is not a fast-forward (divergent histories), Pull returns an error – manual merge with an external Git client is required.

Auth types: - Token: for GitHub/GitLab personal access tokens over HTTPS - Basic: for username/password over HTTPS - SSH: for SSH key authentication (e.g. git@github.com:user/repo.git)

CLI subcommands

All git operations are available from the command line:

hook git status           Show changed files
hook git stage <path>     Stage a specific file
hook git stage --all      Stage all changes
hook git unstage <path>   Unstage a file
hook git commit -m "msg"  Commit staged changes
hook git log [--max N]    Show commit history
hook git diff [path]      Show working directory diff
hook git restore <path>   Discard changes to a file
hook git branch           List branches
hook git branch <name>    Create a new branch
hook git switch <name>    Switch to a branch

See CLI Reference for detailed syntax and output format.

Typical workflows

Manual version control

1. Edit requests in the GUI.
2. Save the collection.
3. Open the Git popup, review status.
4. Click Stage All.
5. Write a commit message and click Commit.
6. Click Push to share.

Automatic version control

Set git_auto_stage=1 and git_auto_commit=1 in hook.conf (or enable them via the Git panel checkboxes). Every time you save a collection or environment (including after imports), Hook automatically stages the file and commits it with a message like auto: update collections/my-api.json.

Team collaboration

1. Configure Remote settings with your repo URL and auth.
2. Click Pull to get the latest changes.
3. Edit, save, stage, commit.
4. Click Push to share your changes.

Discarding changes

To undo local modifications to a file:

1. Open the Git popup, click Refresh.
2. Select the modified file in the Status list.
3. Click Reset File. Confirm in the dialog.
4. The file is restored from the last commit.

To reset an entire directory (e.g. all collections):

1. Select any file in that directory.
2. Click Reset Dir. All modified/deleted files in the directory are restored.

To reset everything: click Reset All (restores all watched files).

Branching for experiments

1. Create a branch: enter name, click Create.
2. Make changes, save, stage, commit.
3. Switch back to main.
4. The main branch is unchanged.

Repository initialization

If the working directory is not a Git repository, Hook initializes one automatically when Git is enabled and settings are saved.

Git button status colors

When Git integration is enabled, the Git toolbar button changes color to reflect the current repository state:

Priority when multiple states apply: Error > Dirty > Ahead > Clean.

Pull check interval

The Git settings panel includes a “Pull check” slider (0-180 minutes, step 5). This controls how often Hook fetches from the remote to check if there are new commits to pull.

• 0 (disabled): no automatic fetch. Fully offline mode.
• 5-180 minutes: Hook fetches from origin at the specified interval and checks how many commits the remote is ahead.

When the pull check interval is enabled (> 0):

• At startup: Hook performs one initial fetch to check for remote changes, regardless of the interval.
• Periodically: every N minutes, Hook fetches again and updates the behind count.

When the remote has commits not yet pulled, a colored notification appears in the center of the main statusbar:

N commit(s) to pull

This notification is visible even when the Git popup is closed.

Note: The fetch operation briefly blocks the UI while contacting the remote. With a minimum interval of 5 minutes, this is rarely noticeable.

Status messages

All git operation messages (stage, unstage, commit, push, pull, etc.) appear directly in the Git popup next to the “Status:” label, instead of in the main statusbar.

Limitations

• Pull only supports fast-forward merges. Divergent histories require manual merge with an external Git client.
• Only local branches are listed. Remote tracking branches are not shown.
• Merge and rebase are not supported from within Hook.