Question 1

What is GitAegis, in one sentence?

Accepted Answer

A native macOS Git client that captures a full recovery capsule of your repository state before a risky operation runs, and refuses to run the operation if that capsule cannot be written.

Question 2

Is it a Git client or a recovery tool?

Accepted Answer

Both, and it has to be both. A recovery layer that only woke up for operations you ran somewhere else would miss most of what happens to a repository. GitAegis does the everyday work (staging by hunk and by line, commits, branches, remotes, merges, rebases, conflicts, worktrees, stashes, submodules, LFS, graph, blame, bisect) and every mutating one of those goes through the same transaction model.

Question 3

Do I need an account?

Accepted Answer

No. You can download GitAegis, point it at a repository and work. Sign in only when you want optional account features; local Git work remains available either way.

Question 4

What does GitAegis change in my repository?

Accepted Answer

It runs the Git commands you asked for, writes recovery refs under refs/aegis/, and keeps capsule data in its own application support directory. It does not rewrite your config, install hooks, or add files to your working tree. Uninstall it and you are left with ordinary Git repositories.

Question 5

What are the five modes?

Accepted Answer

Home (Command-1) is the repository catalogue. Work (Command-2) is status, staging and committing. History (Command-3) is the graph, file history, blame, compare and search. Review (Command-4) is change sets. Doctor (Command-5) is diagnosis, repair, Lost Work and the Flight Recorder timeline. Command-K opens a command palette over real intents rather than a fuzzy list of menu labels.

Question 6

How long is it from download to a first commit?

Accepted Answer

GitAegis reads repositories where they already are. There is no import step and no re-clone. Add a folder from Home, switch to Work, stage by hunk or by line, and commit.

Question 7

Can I keep using my terminal alongside it?

Accepted Answer

Yes, and that is a design assumption rather than a tolerated case. A filesystem watcher feeds the Flight Recorder, so ref, HEAD, index and stash movements you make in a terminal or another tool land on the same timeline as the ones GitAegis performed. Edits to file contents are not timeline events. Those show up in status. An operation you run in the terminal gets no capsule, because nothing was there to take one.

Question 8

Does GitAegis bundle Git?

Accepted Answer

No, and it never downloads one. It runs the Git already installed on your machine: your version, your credential helpers, your SSH configuration, your hooks policy.

Question 9

What Git version do I need?

Accepted Answer

Git 2.38.0 or newer. Below that floor GitAegis tells you at launch rather than failing halfway through an operation.

Question 10

I am on macOS 12 and Git says 2.37.1.

Accepted Answer

That is Apple's Command Line Tools version and it is below the floor. Install a current Git with Homebrew and restart GitAegis so it picks up the new binary. GitAegis will not quietly use a Git older than 2.38.0.

Question 11

Where does GitAegis look for Git?

Accepted Answer

In a fixed set of standard macOS locations, rather than in your shell PATH. That is deliberate: a desktop application launched from the Dock does not inherit your shell profile, so a PATH lookup would make the answer to "which Git ran?" depend on how you started the app. It has a real cost, and it is worth stating: a Git installed only by a version manager or under a custom prefix may not be found, and there is no setting in the app to point at it. If that is your setup, write to support and say so.

Question 12

Which platforms are supported?

Accepted Answer

macOS 12 Monterey or later, on Apple Silicon and Intel. That is the whole list. There is no Windows build and no Linux build to download.

Question 13

Is it Electron?

Accepted Answer

No. The core is Rust on Tauri v2 and the interface is React and TypeScript running in the system webview, so there is no bundled browser engine.

Question 14

How does it handle credentials and SSH keys?

Accepted Answer

It uses your system keychain and your own SSH keys, and it does not store, proxy or transmit them. Subprocesses pin GIT_CONFIG_* and GIT_TERMINAL_PROMPT=0, so a hostile core.fsmonitor in a cloned .git/config cannot execute and Git can never silently block on a hidden password prompt.

Question 15

What exactly does a recovery capsule capture?

Accepted Answer

Six domains: refs, index, staged changes, working changes, untracked files, and operation state. Each one is restorable on its own. You can put the refs back and leave your working tree alone, or the reverse.

Question 16

How are staged and working changes stored?

Accepted Answer

As binary patches: GitAegis runs git diff --cached --binary and git diff --binary at capture time and stores the output. In practice that is content-complete, but it is a patch and not a set of objects, and it is worth knowing which. On a repository too damaged to compute the diff, GitAegis writes an empty patch and records a note in the capsule manifest, so the domain can be present and empty rather than silently wrong.

Question 17

When is a capsule taken?

Accepted Answer

Before the first git command of a risky operation executes. Not after it, not alongside it. Operations the planner rates as safe take no capsule, because there is nothing destructive to roll back, and three operations take none even so: removing a worktree, updating a submodule, and fetching LFS objects.

Question 18

What happens if the capsule cannot be written?

Accepted Answer

The operation is blocked and never runs. This is the part that separates GitAegis from a client that warns you and proceeds. No control in the shipped interface can waive it: there is no checkbox that says proceed anyway.

Question 19

What can GitAegis actually recover?

Accepted Answer

Stated exactly: if a recovery capsule was taken, you can roll the operation back. If a Flight Recorder event captured a state hash, you can roll back to that state. If any reflog entry, ref, branch, stash, or capsule references a commit, Lost Work can recover it. Outside those, it cannot. There is no guaranteed-recovery claim in this product and there never will be.

Question 20

So what can it not recover?

Accepted Answer

Work that never existed as a Git object and was never captured by a capsule: an unsaved editor buffer, a file deleted before GitAegis ever saw the repository, changes made while GitAegis was not running. Also anything an external process destroyed outside the operations GitAegis planned.

Question 21

Is rebase state restored from a capsule?

Accepted Answer

No, and this one catches people. The capsule records that a rebase was in progress and captures the refs and working state around it. It does not rehydrate .git/rebase-merge, and restoring does not put the sequencer back. Recovery from an interrupted rebase is ref-based: you get your branches and your working tree, not a resumable position in the todo list.

Question 22

Does a capsule restore my Git config?

Accepted Answer

No. Config is captured as evidence only. You can see exactly what it was at the time of the operation, which is often the thing you actually needed to know. Putting it back is a decision you make by hand.

Question 23

Can GitAegis bypass .gitattributes content filters?

Accepted Answer

No. Filters declared in .gitattributes cannot be wholesale disabled. If a smudge or clean filter transforms content on checkout, that transformation is a property of the repository, and GitAegis will not quietly work around it. Doctor names the filter when it is implicated in a finding.

Question 24

Can it resume a bisect or a conflicted stash apply?

Accepted Answer

There is no generic resume for either. Both leave states GitAegis can describe precisely (Doctor will tell you where you are and what your options are) but it will not invent a continuation that Git itself does not define.

Question 25

Does it ever run git gc, git prune, or reflog expiry?

Accepted Answer

No. git gc, git prune and git reflog expire are the commands that destroy recoverable objects, and no path in the product runs them. One precision, because you may see the word in the Operation Journal: git remote prune and git worktree prune do run. The first deletes remote-tracking refs, the second deletes stale worktree registrations. Neither deletes a single object.

Question 26

What is Lost Work searching?

Accepted Answer

Seven sources: the HEAD reflog, the stash list, Flight Recorder before-oids, refs/aegis/ recovery refs, capsule bundles, sibling worktree HEADs, and a bounded git fsck --unreachable --dangling. Two caps are worth knowing rather than discovering: the HEAD reflog read is the most recent 40 entries, and the fsck pass stops at a fixed commit budget. When it finds a commit nothing points at, it offers to put a branch back on it.

Question 27

What is Safe Mode?

Accepted Answer

When the index or HEAD cannot be trusted, GitAegis locks out mutating controls instead of letting you make it worse, and pins core.hooksPath to /dev/null so nothing in the repository executes while you are diagnosing it. Reading, inspecting and exporting stay available. Committing your way deeper into the hole does not.

Question 28

What happens if GitAegis crashes mid-operation?

Accepted Answer

Every mutating operation is recorded in the Operation Journal as a transaction. On the next launch, recovery reconciles unfinished transactions and marks anything it cannot safely resolve as requiring intervention, with the plan, the exact commands and the checkpoint attached, so you can see precisely where it stopped.

Question 29

Does it use external diff or merge tools?

Accepted Answer

No, in any mode. Conflict resolution happens inside GitAegis with stage-1/2/3 read, resolution, and sequencer continue, skip or abort. GitAegis does not hand your repository to a binary whose behaviour it cannot reason about.

Question 30

Does the app send anything anywhere?

Accepted Answer

Local Git work stays on your machine and does not require an account. If you choose to sign in, GitAegis contacts only its configured account gateway for the account features you choose. Git traffic still goes directly to the remotes you configured.

Question 31

Is my source code ever uploaded?

Accepted Answer

No. The optional account connection does not upload repository contents, paths, commits, or remote URLs.

Question 32

Where are capsules stored?

Accepted Answer

On your own machine, in the GitAegis application support directory, alongside recovery refs written under refs/aegis/ in the repository itself.

Question 33

What about telemetry?

Accepted Answer

GitAegis does not send telemetry. There is no analytics switch because there is no telemetry collection behind it.

Question 34

Is GitAegis SOC 2 or ISO 27001 certified? Is it GDPR compliant?

Accepted Answer

No certification is claimed here, because none is held. Claiming one before it exists is the kind of thing this product is built not to do.

Question 35

Does this website track me?

Accepted Answer

No. This site runs no analytics script, sets no tracking cookies, and has no cookie banner because there is nothing to consent to.

Question 36

What does the download include?

Accepted Answer

The whole local client. Recovery capsules, the Operation Preview drawer on every dangerous action, Doctor's scan and its repairs, Safe Mode, the Flight Recorder, Lost Work and the Operation Journal are all in it. No safety capability is held back behind a tier.

Question 37

What does it cost?

Accepted Answer

Nothing, and there is no way to pay for it. There is no checkout, no billing provider and no subscription to start.

Question 38

Is there a trial?

Accepted Answer

There is nothing to trial. The macOS edition is free and complete on its own, and it does not expire.

Question 39

Is there a cloud service: capsule backup, multi-device restore?

Accepted Answer

No. The client makes no network requests of its own, and there is no service running behind it to back a capsule up to. Your capsules are on your disk and nowhere else.

Question 40

Are there team features: shared workspaces, org policy, audit, SSO?

Accepted Answer

Not in the product you can download. Change sets exist locally in Review mode; the shared workspace, signed org policy, audit trail, SSO and SCIM that have been described elsewhere are not part of this build.

Question 41

Does it integrate with GitHub or GitLab?

Accepted Answer

Not as a provider integration. Your remotes work exactly as Git remotes: clone, fetch, pull and push, against GitHub, GitLab, Bitbucket, Azure DevOps, Gitea or a bare repository over SSH, using your own credentials. What is not there is pull requests, merge requests, reviews and CI status inside GitAegis.

Question 42

Is there an AI assistant?

Accepted Answer

No. No model provider is wired into the shipping build, so there is nothing to enable and no data boundary to consent to.

Question 43

Does it update itself?

Accepted Answer

No. GitAegis does not currently include an updater. You replace it the way you installed it.

Question 44

GitAegis says it cannot find a usable Git.

Accepted Answer

It found no Git, or found one below 2.38.0. Check git --version in a terminal, install or upgrade Git, and restart GitAegis so it re-detects. On macOS 12 specifically, Apple's Command Line Tools ship 2.37.1: install a current Git with Homebrew. If your Git lives somewhere unusual, see the platform question above: GitAegis looks in standard locations rather than in your PATH.

Question 45

A push fails with an authentication error, but the terminal works.

Accepted Answer

GitAegis pins GIT_TERMINAL_PROMPT=0, so Git cannot fall back to an interactive prompt. It fails visibly instead of hanging on a prompt you cannot see. Check that your credential helper is configured in your system keychain and that your SSH key is loaded in your agent.

Question 46

The app opened in Safe Mode and the buttons are disabled.

Accepted Answer

Safe Mode means the index or HEAD could not be trusted. That is the application stopping you committing on top of a damaged state. Switch to Doctor, read the findings and the evidence behind them, and apply the proposed repair, which takes a capsule before it runs.

Question 47

An operation is marked as requiring intervention after a crash.

Accepted Answer

Recovery found a transaction it could not safely resolve on its own. Open the journal entry: it holds the intent, the exact commands, the checkpoint and how far it got. From there you can roll back to the checkpoint or complete the operation deliberately.

Question 48

A file disappeared and it was never committed.

Accepted Answer

Open Doctor and run Lost Work. If the file was untracked and a capsule captured it (capsules include the untracked domain) it is restorable from that capsule. If no capsule ever ran over it and it was never a Git object, nothing wrote it down, and no tool can produce it. That is the boundary, and you will hear it on the first reply rather than the fourth.

Question 49

A large repository is slow to open.

Accepted Answer

Check for a very large packed-refs file, deep submodule recursion, or LFS objects being accounted for; Doctor reports repository shape. If the numbers look reasonable and it is still slow, generate a support bundle and send it. That is a bug, not a configuration problem.

Question 50

How do I report a bug?

Accepted Answer

There is a paste-ready block on the contact page: version, macOS version, Git version, repository shape, what you did, what you expected, what happened, and whether a support bundle is attached. Bundles are written to your own disk, secret-scanned before you see them, and reviewed by you before they leave your machine.

Frequently asked questions

Getting started

Git and the platform

Recovery and its limits

Privacy and data

What ships today

Troubleshooting

Not answered here?

A recovery capsule before every risky Git operation.