Everything GitBoxIt is built to help you do.

What GitBoxIt Can Do

• Manage many repositories from one sidebar.
• Group repositories by parent folder and auto-discover nested repos.
• Show incoming, outgoing, and dirty status badges.
• Browse commits, tags, changed files, and diffs.
• Compare the current branch with a remote branch.
• Manage working tree files, including untracked files inside new folders.
• Create commits, amend commits, stash changes, and discard changes.
• Resolve merge, rebase, and stash conflicts in a dedicated tab.
• Create branches, rename branches, merge, rebase, cherry-pick, and apply patches.
• Manage remotes and upstream configuration.
• Edit root Markdown files.
• Run Git commands in the built-in terminal.

First-Time Setup

GitBoxIt runs inside Apple’s App Sandbox, so Git operations may require explicit access to local resources.

1. Add a repository or a folder containing repositories.
2. Open Settings.
3. Set Git user name and email.
4. Grant SSH folder access if you use SSH remotes.
5. Optionally choose a global gitignore file.

Sidebar

Adding Repositories

• Click `+` to add a repository or a folder.
• You can drag a repository or folder from Finder into the sidebar.

Groups

• Adding a parent folder creates a group.
• The app scans that folder for nested Git repositories.
• Group contents refresh automatically when repositories are added or removed.
• Groups and nested folders can be expanded or collapsed.

Badges and Actions

• Green badge: incoming commits available.
• Orange badge: outgoing commits not yet pushed.
• Red badge: dirty working tree.
• Open repos or groups in Finder or Terminal.
• Remove repos or groups from the app.
• Pull all repositories that have incoming changes.

Top Toolbar

• Left picker: current local branch.
• Pull, Push, Tag, Merge, and Rebase actions.
• Right picker: compare branch.
• Search field: author, message, hash, filename.

Push Behavior

• Standard push uses the configured upstream.
• Force Push is available from the Push button context menu.
• If the remote rejects a push, the app can prompt for force-push confirmation.

Compare Branch

• The right picker compares the current branch against a remote branch.
• The first item is `-`, which means no compare branch.
• When comparison is active, commit list rows can show incoming or outgoing markers.

Commit Tab

• Inspect commit history, metadata, changed files, and diffs.
• See message, author, date, tags, and compare markers.
• Create a new branch from a selected commit.
• Cherry-pick the commit.
• Apply a patch.
• Soft reset to the commit.
• Hard reset to the commit.

Working Tree Tab

Files List

• Modified files.
• Added files.
• Deleted files.
• Conflicted files.
• Staged files.
• Unstaged files.
• Untracked files.
• Untracked folders are expanded into the actual file paths.

Actions

• `Create Patch...`
• `Stash`
• `Discard`
• `.gitignore`

Commit Flow

• Select at least one file.
• Enter a non-empty commit message.
• Optionally enable `Amend`.
• Click `Commit`.

Stash and Conflicts

Stash

• View available stash entries.
• Inspect files inside the selected stash.
• View diffs for stash files.
• Apply, Pop, Drop, or Clear stash entries.
• Stash selected checked files with an optional message.

Conflicts

• Review conflicted files.
• Use the working copy editor.
• Inspect Ours and Theirs panes.
• Move between conflicts with Prev and Next.
• Use Keep Ours, Keep Theirs, Save, and Mark Resolved.

Tags, Remotes, Markdown, and Terminal

Tags

• Enter one or more tags separated by spaces, commas, or new lines.
• Empty input removes existing tags from the target commit.

Remotes

• View fetch and push URLs.
• Fetch from a selected remote.
• Set upstream to a selected remote.
• Add and remove remotes.

Markdown and Terminal

• Edit root Markdown files in Edit, Preview, or Split mode.
• Save and reload Markdown content.
• Use the built-in terminal for Git commands in the selected repository.

Settings and Shortcuts

Settings

• Set `user.name` and `user.email`.
• Grant access to `~/.ssh` for Apple App Sandbox builds.
• Choose, edit, and save a global gitignore path.

Shortcuts

• `Cmd-O`: Add Repository
• `Cmd-R`: Pull
• `Shift-Cmd-P`: Push
• `Cmd-,`: Settings
• `Cmd-?`: Help

Troubleshooting

SSH Operations Fail

• Confirm SSH folder access is granted in Settings.
• Confirm your SSH keys and config exist in `~/.ssh`.
• Confirm network or VPN access to the Git host.

Global Gitignore Cannot Be Saved

• Re-select the gitignore file in Settings.
• Save Settings again so sandbox access can be refreshed.

No Diff Appears

• The file may be binary.
• The file may be too large for inline rendering.
• Try another changed file to confirm the diff pipeline is working.

Commit Fails Due to Identity

• Open Settings.
• Set a valid Git user name and email.
• Retry the commit.