Missing features / edge-case handling in gitoxide compared to native git client

[Sampo Kivistö (Havunen)]

Hey,

We are implementing GitComet https://github.com/Auto-Explore/GitComet - Rust based Git GUI and under the hood we would like to utilize gitoxide as much as possible. However, there are certain functionality that has not been implemented as well as certain edge case handling that are missing so we had to fallback native system git binary instead.

This is AI generated analysis of the missing features. It would be awesome if these issues can be implemented.

GitComet gix migration gaps

This is the current inventory of production git subprocess behavior that
prevents GitComet from using the gix library alone. It was reviewed against
GitComet bf048db2 and the local gitoxide checkout 2315ede71 (gix 0.85.0).

It is deliberately an API and behavior inventory, not a count of
Command::new("git") literals. Most backend commands are created by
GixRepo::git_workdir_cmd() in
crates/gitcomet-git-gix/src/repo/mod.rs; a literal-only scoreboard does not
measure the real migration surface.

Scope and terminology

Included: every production subprocess in the repository backend, clone
effect, setup/uninstall mode, standalone difftool mode, and CLI configuration
lookup. Test fixtures, integration tests, and perf_app_launch are excluded
from the runtime blocker list.

Each entry is classified as one of:

Status	Meaning
GitComet migration	The public API exists now; GitComet can replace the process with application-side composition.
Feature gate	The necessary gix plumbing exists, but GitComet's dependency features do not expose it.
Upstream workflow gap	Public low-level pieces may exist, but gix lacks the Git-compatible workflow/API GitComet needs.
Integration retention	gix can perform related Git work, but this process owns GitComet-specific external-process behavior.

GitComet enables max-performance-safe, comfort, basic,
auto-chain-error, status, blame, and sha1
(Cargo.toml). It does not enable
blocking-network-client or worktree-mutation. The two missing feature
groups are important constraints, not upstream gix gaps.

Current gix capabilities that should not be listed as missing

The previous inventory overstated several gaps. These are present in public
gix APIs, although a replacement still needs GitComet implementation and
parity tests.

GitComet use	Current public capability	Migration notes
Repository initialization	gix::init() / gix::init_bare()	Available for test and tooling fixtures; GitComet has no production git init blocker.
Read/update repository configuration	Repository::config_snapshot_mut(), SnapshotMut::{set_value,append_config,commit} and gix_config::File mutation	Covers local config updates, upstream keys, and section removal. Global/system configuration needs explicit file/scope selection and GitComet must preserve its current multi-value and uninstall safeguards.
HEAD, revision resolution, ancestry	Repository::head(), rev_parse_single(), merge_base()	Replaces the backend fallback uses of symbolic-ref, rev-parse, and merge-base --is-ancestor after preserving their corrupt/unborn-HEAD error behavior.
Refs, local tags, and local branch deletion	Reference iteration/mutation and Repository::tag()	Local tag create/list/delete and force branch deletion have building blocks now. Signed tags/commits and hook behavior remain separate gaps.
Remote and branch configuration	Remote::{save_to,save_as_to,with_url,with_push_url} plus config mutation	Can replace remote add/set-url and upstream set/unset once GitComet owns atomic config-file persistence and cleanup semantics.
Worktree enumeration	Repository::worktrees() / worktree proxies	A structured adapter can replace git worktree list --porcelain -z; creating or deleting linked worktrees is still missing.
Local branch/ref enumeration	Reference iteration, remote-tracking lookup, revision walks	Can replace for-each-ref; GitComet already has a gix fallback for branch divergence. A batch implementation and caching are needed for large repositories.
Low-level index edits	gix-index entry mutation and index writing	This corrects the former claim that individual entry mutation is absent. gix still lacks a repository-level git add/git rm workflow that hashes worktree data, applies filters/ignores, updates stat data, resolves conflicts, and commits the index safely.

Evidence: gitoxide/gix/src/lib.rs, repository/config/, repository/object.rs,
repository/reference.rs, repository/revision.rs, repository/worktree.rs,
remote/{build,save}.rs, and gix-index/src/access/mod.rs.

Highest-priority blockers

1. Push and remote writes - upstream workflow gap

Consumers: repo/remotes.rs, repo/tags.rs.

GitComet uses push, --set-upstream, implicit and explicit
--force-with-lease, --delete, normal refspecs, and tag push/delete. gix
does not provide push plumbing: gix-protocol::Command currently exposes
LsRefs and Fetch, not send-pack/receive-pack. crate-status.md still
marks push as incomplete.

Required upstream behavior:

• connect, advertise, negotiate, pack, and update refs through receive-pack;
• parse report-status and sideband failures;
• support create/update/delete refspecs, explicit and implicit force leases,
  atomic updates, and push options;
• expose structured per-ref results suitable for the UI;
• allow GitComet to persist upstream tracking only after a successful push.

The important user-visible cases are a stale explicit lease, a missing remote
branch, a HEAD:refs/heads/<branch> source, deleting remote branches/tags,
and preserving rejected-ref diagnostics.

2. Network access and fetch persistence - feature gate plus upstream gap

Consumers: repo/remotes.rs, repo/tags.rs, clone effect.

gix supports clone/fetch/ls-refs plumbing, but GitComet has no
network-client feature enabled. Enabling blocking-network-client (and a
chosen HTTP transport) is a GitComet dependency/configuration change.

Even then, GitComet cannot directly replace its safe-push fetch:

• gix does not write FETCH_HEAD (crate-status.md);
• GitComet intentionally fetches a branch with --no-tags --refmap= and then
  resolves FETCH_HEAD^{commit};
• fetch --all and prune behavior need application orchestration and
  Git-compatible remote/refspec choices;
• protocol-v1 stateful ssh, git, and file fetches may hang
  (SHORTCOMINGS.md).

Do not describe push as a prerequisite for pull. Fetch plus either merge or
rebase is the dependency chain; push is independent remote-write work.

3. Checkout, reset, restore, and clean - feature gate plus upstream workflow gap

Consumers: repo/porcelain.rs, repo/history.rs, repo/discard.rs,
repo/blame.rs, repo/submodules.rs.

GitComet runs branch and detached checkout, tracking-branch checkout,
soft/mixed/hard reset, path restore, conflict-side/base checkout, removal of
staged additions, path-scoped clean, and forced submodule restore.

worktree-mutation is not enabled, so GitComet currently cannot use the
low-level checkout facilities. More importantly, gitoxide still marks
checkout/switch/restore/reset orchestration as incomplete. A safe replacement
must compose refs, HEAD, index, worktree writes, clean/smudge filters,
conflict stages, ORIG_HEAD, sparse/worktree configuration, and overwrite
protection. Path-scoped discard must continue to distinguish tracked,
untracked, staged-added, conflicted, and submodule paths exactly as
discard_worktree_changes_impl() does.

4. Index-to-worktree porcelain - upstream workflow gap

Consumers: staging, unstage, mergetool completion, conflict-side/base
checkout, submodule pointer changes, and deletion in porcelain.rs,
mergetool.rs, blame.rs, and submodules.rs.

The missing item is not low-level index mutation. It is a supported
repository-level add/remove/resolve workflow:

• hash a worktree file and run configured clean filters;
• honor ignore and pathspec rules for add -A;
• write mode, stat, intent-to-add, gitlink, and conflict-stage state;
• remove selected entries while choosing whether to retain worktree data;
• lock and write the index safely, including split-index considerations;
• turn stages 1/2/3 into a resolved stage-0 entry.

Until that exists, git add, git rm, git rm --cached, and their
path-batching behavior remain subprocesses. The consumers should remain one
shared gap, not separate duplicate gaps.

5. Sequencer and merge workflows - upstream workflow gap

Consumers: repo/history.rs, repo/porcelain.rs, repo/remotes.rs.

GitComet has grown beyond a simple rebase --continue wrapper. It supports
interactive rebase state, reword/squash/fixup/drop planning, merge-mainline
cherry-picks, --no-commit, automatic skipping of truly empty picks, and
careful distinction between conflict pauses and hook/signer failures. It also
uses merge, squash merge, and abort paths.

gix has merge-base and low-level merge plumbing, but the merge feature is
not enabled in GitComet and gitoxide still marks merge, rebase,
cherry-pick/revert, and their persisted/resumable workflows incomplete.

Required behavior includes:

• merge fast-forward/no-fast-forward/squash/no-commit semantics;
• index conflict entries and MERGE_HEAD, MERGE_MSG, MERGE_MODE,
  ORIG_HEAD, continue, and abort;
• a sequencer with rebase/cherry-pick/revert continue/skip/abort/quit;
• mainline selection for merge commits and correct empty-pick handling;
• rebase todo editing, autostash/rerere where requested, and safe recovery
  from existing Git-created state;
• hooks, signing, and reflog messages at the same transaction boundaries.

The special git commit-tree plus compare-and-swap git update-ref squash
path in history.rs is also part of this group: public commit/ref primitives
exist, but preserving signing, hooks, reflogs, and atomic expected-old updates
requires a deliberate GitComet composition or a higher-level API.

6. Stash, mailbox patches, and patch application - upstream workflow gap

Consumers: repo/porcelain.rs, repo/patch.rs.

GitComet uses stash push with optional untracked files, apply with a
preflight, and drop. It also exports format-patch, applies mailbox patches
with am --3way, and applies/reverses unified patches to either the index or
worktree using --recount --whitespace=nowarn.

Gitoxide still marks stash, am, and apply workflow composition as
incomplete. Required work includes stash commit/reflog construction, optional
untracked parent handling, preflight overwrite checks, three-way conflict
state, textual and binary patch parsing/application, mailbox metadata, and
index/worktree destinations. format-patch additionally needs stable
email-style headers and Git binary-patch output.

7. Worktree and submodule mutation - upstream workflow gap

Consumers: repo/worktrees.rs, repo/submodules.rs, repo/discard.rs.

gix can list worktrees and read/enumerate submodules; it cannot create,
remove, move, repair, or prune linked worktrees. It also lacks submodule
editing and lifecycle workflows.

GitComet's submodule path is broader than the old inventory recorded:

• trusted local-file transport approval;
• submodule add with branch/name/force;
• recursively initialize nested submodules;
• detach a nested checkout and stage the gitlink;
• deinitialize, remove the gitlink, and clean .git/modules plus local
  config;
• restore recorded submodule commits during discard.

A gix replacement must preserve these trust checks, recursive behavior,
.gitmodules and local-config updates, gitlink index updates, nested clone/
fetch/checkout, and cleanup on failure.

Important secondary gaps

Operation and current consumers	Status	Missing behavior
git commit, --amend in porcelain.rs	Upstream workflow gap	Public commit creation exists, but amend composition, hook execution, signing, message/template handling, and merge-state commits need parity. Hooks are explicitly incomplete in crate-status.md.
git blame --line-porcelain [--contents -] in blame.rs	Upstream workflow gap	Repository::blame_file() handles committed content. There is no public arbitrary-content/worktree blame that produces virtual “not committed yet” attribution and follows historical paths.
git log --follow, diff-tree -M in log.rs	GitComet migration / upstream convenience gap	gix has revision walking and rename/copy diff primitives, but no ready-made path-following walk. GitComet can compose one, but needs exact rename-threshold, deletion-to-destination, pagination, and merge-history semantics.
Unified diff, show, commit-range output, and submodule --numstat/--name-status summaries in diff.rs and submodules.rs	GitComet migration	gix has tree/blob/index/worktree diff primitives and rewrite tracking. The missing piece is GitComet's complete text and summary renderer: headers, modes, binary representation, filtered ranges, CR-at-EOL policy, rename policy, and parser compatibility. This should not be filed as missing diff plumbing.
git cat-file blob <oid> preview streaming in diff.rs	GitComet migration	gix can read objects directly. Replace the child-process stream with an ODB-to-file/cache adapter that retains the current bounded-memory behavior and error handling for missing or non-blob objects.
Remote tag listing in tags.rs	Feature gate plus integration	gix ls-refs exists after network features are enabled. GitComet needs a cancellable per-remote adapter, tag filtering/peeling policy, partial remote failures, and a solution for protocol-v1 reliability.
Remote add/remove/set-url and upstream set/unset	GitComet migration	Current config/remote APIs supply building blocks. Implement atomic config writes, default fetch refspecs, remote-tracking-ref cleanup, push URLs, and multi-value configuration behavior.
Branch prune and branch divergence display	GitComet migration	gix can iterate refs and walk ancestry. Build batched/cached divergence and merged-branch filtering before replacing for-each-ref; avoid one expensive walk per branch.
Gitlink status supplement in status.rs	Parity gap	Primary status already uses gix. Retain the porcelain-v2 subprocess only until gix tree-vs-index recursive submodule status matches the needed entries. Treat it as a focused parity test, not a general status gap.

Production subprocesses outside the repository backend

Location	Command family	Classification	Reason to retain or migrate
crates/gitcomet-state/src/store/effects/clone.rs	git clone --progress	Integration retention	gix clone plumbing exists after network features are enabled. This process additionally owns askpass/SSH-passphrase prompting, streamed stderr progress, child-process cancellation, and cleanup of a partial destination. A migration is viable only after preserving those UI contracts.
crates/gitcomet/src/setup_mode.rs	git config global/local get, set, add, unset	GitComet migration	gix config APIs can edit explicit repository config. Setup/uninstall must still safely manage global scope, multiple values, prior-user-value backups, and conditional removal; these are application semantics.
crates/gitcomet/src/cli/git_config.rs	git config --get, rev-parse --show-toplevel	GitComet migration	gix discovery, rev-parse, and config reads can replace these fallback lookups where the candidate path is a repository. Preserve the current “not a repo/no value” behavior.
crates/gitcomet/src/difftool_mode.rs	git diff --no-index --no-ext-diff	Integration retention	This compares arbitrary files/directories, including Git-provided temporary inputs and externally visible unified-diff formatting. gix blob-diff primitives are useful, but this is not a repository gix API gap and needs a dedicated non-repository renderer.

Excluded process uses

The following are not runtime blockers and must not be counted against the
gix migration inventory:

• gitcomet-git-gix integration/unit tests and tests under other crates;
• merge-fixture test setup in extract_fixtures_mode.rs;
• perf_app_launch repository-fixture creation;
• test-only isolated Git configuration in repo_monitor.rs and clone tests.

Recommended migration order

1. Remove subprocesses already covered by public gix: HEAD/revision/
   ancestry fallbacks, worktree listing, local tag operations, branch safe
   delete composition, config section cleanup, and selected configuration
   lookups. Add parity tests before each removal.
2. Enable and evaluate worktree-mutation for narrow, safe checkout/
   restore experiments. Keep destructive reset, clean, and submodule restore
   behind explicit parity coverage.
3. Enable a blocking network client and transport in an isolated change.
   Prototype fetch and ls-refs with GitComet's progress/cancellation/auth
   requirements; do not migrate safe-push until FETCH_HEAD is avoided or
   upstream support exists.
4. Upstream-focus the shared workflows: repository-level index mutation,
   sequencer/merge state, stash/apply, worktree/submodule mutation, hooks,
   and push.
5. Treat unified diff, path-following history, clone integration, and
   non-repository difftool as GitComet composition projects, contributing
   upstream APIs only where repeated application code exposes a genuine
   library boundary.

Source checklist

The inventory was reconciled against these GitComet call sites:

• crates/gitcomet-git-gix/src/repo/{porcelain,history,remotes,tags,worktrees, submodules,discard,diff,blame,log,patch,mergetool,status,git_ops}.rs
• crates/gitcomet-state/src/store/effects/clone.rs
• crates/gitcomet/src/{setup_mode,difftool_mode}.rs
• crates/gitcomet/src/cli/git_config.rs

Key gitoxide evidence:

• crate-status.md - workflow, remote, worktree, config, and hook status;
• SHORTCOMINGS.md - protocol-v1 stateful-fetch limitation;
• gix/src/{lib,clone,remote,repository,reference,worktree}.rs;
• gix-index/src/access/mod.rs and gix-config/src/file/access/mutate.rs.

[Sebastian Thiel (Byron)]

Thanks for the feedback!

Can you add a checklist to the issue, maybe even in a tree structure?

PS: I wish LLMs would stop writing like them, I want to throw up when I see 'gap' and 'wedge' these days 🤦‍♂️.