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_hostsonly 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.