Docs

Short guides to everything in Histq.

Install & updates

  • Download the DMG from Releases, drag Histq to Applications.
  • Requirements: macOS 15 or later on Apple silicon, and git 2.36 or later. The git from the Command Line Tools or from Homebrew works.
  • Git binary: Histq finds git on its own; pick another one in Settings › General.
  • Updates: through Sparkle. Check by hand with Histq › Check for Updates…

Open & clone

  • Open: ⌘O, or Open… on the welcome screen, then pick a repository folder.
  • Clone: File › Clone… or the welcome screen's Clone card: a URL and a destination folder.
  • Create: Init… on the welcome screen makes a new repository.
  • Recent: recent repositories are on the welcome screen. Right-click one to remove it.

Commit graph & search

  • Graph: branches, tags, stashes, remotes and worktrees in one graph, fast on tens of thousands of commits.
  • Search: ⌘F slides a bar up at the bottom of the graph. It finds commits by subject or by part of the hash; the other rows are dimmed.
  • Matches: Return and Shift-Return move between them, Esc closes the bar.
  • Layout: row height (compact, regular, comfortable) and the message, author and date columns are in Settings › Appearance.
  • Narrow graph: lanes fold into each other, and branch and tag labels shrink to "…", then to an icon.
  • Faded label: a selected commit with no branch label of its own shows a faded label of its branch.

Commit details

  • A click shows the commit's subject, body, author, committer and date at once, then its changed files.
  • SHA: copy it with its button. Parents jump to their row in the graph.
  • Diff: select a file to see its diff in place of the graph; Esc goes back.
  • Explain: asks your AI provider to explain the commit (see AI).

Stage & commit

  • Working tree: conflicted, unstaged and staged files, each in its own card.
  • Diff: Diff or Full file, with syntax colors. ⌘C copies the selected lines.
  • Hunks and lines: stage, unstage or discard a hunk, or only its selected lines.
  • Commit box: summary with a 72-character counter, description and Amend. Commit with ⌘↩.
  • Generate Message: writes a commit message from the staged diff with your AI provider.

Interactive rebase

  • Right-click a commit, Interactive Rebase from Here…: it lists that commit and every later one of the current branch.
  • Actions: pick, reword, edit, squash, fixup or drop. Drag rows to reorder them.
  • Reword: edit the message in the row; no editor opens.
  • Squash: select a run of commits, Squash N Commits…, and edit the combined message.

Conflicts

  • Editor: panes A and B show both sides, Output shows the merge, with "conflict k of N".
  • Resolve: tick lines (or a whole side) from A and B into Output, or edit Output by hand.
  • Save: with conflicts left, it asks: Save Output (write it and mark the file resolved) or Create Conflict Chunks (write git's conflict markers, the file stays conflicted).
  • Reset: clears your choices. Leaving the editor with unsaved choices asks first.
  • Suggest Resolution: asks your AI provider for the current conflict. Open in external merge tool uses the tool set in Settings › General, else the one your git config names.

Undo & redo

  • ⌘Z and ⇧⌘Z, also in the command palette.
  • Undoable: commit, amend, checkout, reset, merge, rebase, cherry-pick, revert, branch create, delete and rename, and discard.
  • Not undoable: push, pull, fetch, and remote branch and tag changes.
  • Safe: undo refuses when the repository changed since (for example, a commit made in a terminal), instead of overwriting work.

Worktrees

  • The Worktrees card in the sidebar lists linked worktrees.
  • Add: Add Worktree…, or from a commit or a branch's menu.
  • Open a worktree in a new tab, Remove it, or Prune Worktrees.
  • Tabs of one repository's worktrees sit side by side as a tab group.

Tabs & sessions

  • Position: a tab strip under the toolbar, or vertical tabs on the left. Set it in Settings › Appearance › Tab position.
  • New tab ⌘T, close ⌘W, reopen the last closed tab ⇧⌘T.
  • Groups: the worktrees of one repository are grouped under its name and color. Click the name to collapse the group.
  • Profiles: each tab has its own profile, picked from the profile menu in the toolbar, after the branch menu.
  • Session: windows and tabs are restored at launch. A folder that is gone shows as "Repo not found".

Command palette

  • Open it with ⌘K. Type to search, Up / Down to choose, Return to run, Esc to close.
  • Sections: Repository, Checkout, Tabs, Histq and Operations.
  • Check out a local or remote branch, switch tabs, open a repository or a Settings page, or move the tabs.
  • Repository operations ask the same confirmations as the menus.

Profiles & SSH

  • Profile: a name and color, a commit identity, signing, an SSH key and a GitHub account. Create profiles in Settings › Profiles.
  • Signing: none, GPG or SSH, passed to git for the profile's tabs only. Your git config is not changed.
  • SSH key: ssh-agent (with ~/.ssh/config) or a key file, in Settings › SSH. Generate Key… makes an ed25519 key without a passphrase.
  • Passphrase: Histq runs ssh in batch mode, so keys with a passphrase need ssh-agent.
  • Trust Host: an unknown SSH host shows its fingerprint first; it is added to known_hosts only when you confirm.
  • New tabs: use their repository's last profile, else the default profile.

GitHub

  • Token: in Settings › Integrations, per profile: paste a personal access token, or Import the GitHub CLI's token. github.com or a GitHub Enterprise Server host.
  • Lists: My PRs, Review requested, All open and Issues assigned to me, in the sidebar's PRs tab.
  • Pull request: Conversation, Commits, Files changed and Checks tabs.
  • Writes: create a pull request, comment, review, merge, close or reopen, only when you click.
  • Bodies are shown with JavaScript off and no remote content. Links open in your browser.

AI

  • Providers: OpenAI, Anthropic, Google Gemini, xAI, or a custom OpenAI-compatible server, with your own API key.
  • Actions: Generate Message (commit box), Explain (a commit or your changes), Suggest Resolution (conflict editor).
  • Preview: the answer changes nothing until you click Apply.
  • Settings › AI: Test connection and Load models.
  • Languages: explanations and commit messages each have their own response language.

Terminal

  • ⌃` shows or hides a terminal drawer at the bottom of the repository tab.
  • One terminal per tab, started in the repository folder with the tab's profile (identity, signing, SSH key).
  • The shell keeps running until its tab or window closes.
  • Settings › Terminal: font, size, cursor, scrollback, bold text, shell, and opening a terminal with each new tab.

Keyboard shortcuts

  • Windows and tabs: new window ⌘N, new tab ⌘T, close tab ⌘W, reopen closed tab ⇧⌘T, close window ⇧⌘W.
  • Repository: open ⌘O, command palette ⌘K, find commits ⌘F, terminal ⌃`.
  • Edit: undo ⌘Z, redo ⇧⌘Z. Commit box: commit ⌘↩.
  • Settings: ⌘,. The menus show the window, repository and edit keys next to their commands.

Settings

  • Open with ⌘,. Histq is dark only.
  • General: default profile, pull mode, automatic fetch, merge tool and git binary.
  • Appearance: tab position, avatars, date format, row height and graph columns.
  • Profiles and SSH: identity, signing and SSH keys of each profile.
  • Integrations and AI: the GitHub token of each profile; the AI provider, key, model and languages.
  • Terminal: font, cursor, scrollback and shell.