Skip to content

git engine

Jump to bottom
github-actions[bot] edited this page Sep 21, 2026 · 10 revisions

Git Engine

The Rust native module that powers Git operations in GitNotēs. See Architecture for context.

Overview

GitNotēs uses a custom Rust Git library (git2-based) compiled as a native module and exposed to JavaScript via Turbo Module (New Architecture). This provides significant performance benefits over pure-JavaScript git implementations for large repositories.

Package name: gitnotes-git-engine (local npm package at modules/GitEngine/)

Module Location

gitnotes/
├── modules/
│   └── GitEngine/               # Rust crate (git2-based)
│       ├── Cargo.toml           # Rust dependencies (git2, serde, etc.)
│       └── src/                 # Rust source (lib.rs + ops modules)
├── src/
│   └── services/
│       └── git/
│           └── engine/
│               └── GitEngine.ts  # JavaScript/TypeScript facade
└── package.json

The Rust crate's internal module structure (lib.rs, git_ops.rs, etc.) is an implementation detail — consult the crate directly for the canonical list.

TypeScript Bindings

File: src/services/git/engine/GitEngine.ts

Exports the native module as GitEngine. The JS side imports it as:

import * as GitEngine from './engine/GitEngine';

Exported Operations

These are the JS facade operations in src/services/git/engine/GitEngine.ts. The facade is a typed wrapper around the native Rust module. All ops run on the native engine queue under a per-repo flock.

Clone & Init

GitEngine.clone(url: string, dest: string, repoId?: string): Promise<string>

Clones a repository to the local dest path.

Parameters:

  • url — Git remote URL
  • dest — local destination path
  • repoId — optional repo identifier

Returns: Promise<string> — final path after clone

GitEngine.initRepo(repoPath: string, bare: boolean): Promise<void>

Initializes a new repository (bare = true creates a push-ready local remote).

Repo Maintenance

GitEngine.removeRepo(repoPath: string): Promise<void>

Removes a cloned repository and its working tree.

GitEngine.repairRepo(repoPath: string): Promise<RepairReport>

Repairs a corrupted repository. Returns a report listing what was corrupted, repaired, and unrecoverable.

Status & Diff

GitEngine.status(repoId: string, repoPath: string): Promise<RepoStatus>

Returns the current branch, ahead/behind count, and branch list for a repo.

Returns:

interface RepoStatus {
  branch: string;
  branches: BranchInfo[];
  ahead: number;
  behind: number;
  currentBranch: string;
}

GitEngine.statuses(repoPath: string): Promise<FileStatus[]>

Lists the status of all files — staged, modified, untracked.

GitEngine.diffAll(repoPath: string): Promise<FileDiff[]>

Computes a diff of all changed files between HEAD and working tree.

GitEngine.diffFile(repoPath: string, filePath: string): Promise<FileDiff>

Computes a diff for a single file.

Staging

GitEngine.stage(repoPath: string, paths: string[]): Promise<void>

Stages file changes for the next commit.

GitEngine.unstage(repoPath: string, paths: string[]): Promise<void>

Unstages files.

GitEngine.remove(repoPath: string, paths: string[], keepWorktree?: boolean): Promise<void>

Removes files from the repository. keepWorktree preserves the working tree file.

GitEngine.discardFiles(repoPath: string, paths: string[]): Promise<void>

Discards working tree changes for the given files (git checkout --).

GitEngine.stageFileLines(repoPath: string, filePath: string, hunks: HunkSelection[]): Promise<void>

Line-level partial staging — stage only selected diff hunks.

Commits

GitEngine.commit(repoPath: string, message: string, author: Author): Promise<CommitInfo>

Creates a commit with the staged changes.

Parameters:

  • repoPath — local repository path
  • message — commit message
  • author — { name: string; email: string }

Returns: Promise<CommitInfo> — commit SHA, message, author, timestamp

GitEngine.log(repoPath: string, limit?: number): Promise<CommitInfo[]>

Returns recent commits (default limit: 50).

GitEngine.commitDiff(repoPath: string, commitId: string): Promise<FileDiff[]>

Per-file diff of one commit against its first parent (git show-style).

GitEngine.checkoutCommit(repoPath: string, commitId: string): Promise<void>

Detaches HEAD at a commit (git checkout <commit>). Rejected if tracked files have staged/unstaged changes.

GitEngine.resetSoft(repoPath: string, commitId: string): Promise<void>

Moves HEAD to a commit, keeping index + working tree (git reset --soft).

GitEngine.revertCommit(repoPath: string, commitId: string, author: Author): Promise<CommitInfo>

git revert a commit. Merge commits are rejected.

Conflicts

GitEngine.conflicts(repoPath: string): Promise<ConflictEntry[]>

Lists currently conflicted files.

GitEngine.resolveConflict(repoPath: string, filePath: string): Promise<void>

Marks a conflicted file as resolved.

GitEngine.getConflictBlobs(repoPath: string, filePath: string): Promise<ConflictBlobs>

Returns the ours, theirs, and base blob content for a conflicted file (for unified-editor conflict UI).

GitEngine.markConflictResolved(repoPath: string, filePath: string): Promise<void>

Marks a conflicted path resolved by staging its working tree content as final.

Network

GitEngine.fetch(repoPath: string, remoteName?: string, repoId?: string | null): Promise<void>

Fetches from a remote.

GitEngine.pull(repoPath: string, remoteName?: string, repoId?: string | null): Promise<PullResult>

Pulls changes from the remote. The native module returns { kind, message, conflicts }; the facade maps FastForward, UpToDate, and Merged to { ok: true } and all other pull kinds to { ok: false, error }.

GitEngine.push(repoPath: string, remoteName?: string, repoId?: string | null): Promise<PushResult>

Pushes the current branch. Force-push is deliberately NOT exposed — the facade hardcodes force: false. Returns { ok: boolean; error?: string }.

GitEngine.pushWithIntegrate(repoPath: string, remoteName?: string, repoId?: string | null): Promise<PushIntegrateResult>

Pushes with transparent fetch + integrate (rebase or merge) when non-fast-forward. Returns { ok, error?, conflicts, pushed, integrated }.

Branches

GitEngine.listBranches(repoPath: string, remoteName?: string): Promise<BranchInfo[]>

Lists all branches.

GitEngine.createBranch(repoPath: string, name: string, source?: string): Promise<BranchInfo>

Creates a new branch.

GitEngine.checkoutBranch(repoPath: string, name: string, remoteName?: string): Promise<void>

Checks out a branch. If checkout fails because the remote tracking ref is missing, callers should fetch from the remote first and retry.

Note: For remote-to-local checkout, callers (e.g., GitBranchCoordinator) handle the fetch-and-retry logic. See GitBranchCoordinator.checkout() for the full remote branch checkout flow.

GitEngine.deleteBranch(repoPath: string, name: string): Promise<void>

Deletes a branch.

GitEngine.renameBranch(repoPath: string, name: string, newName: string): Promise<BranchInfo>

Renames a branch.

Remotes

GitEngine.listRemotes(repoPath: string): Promise<RemoteInfo[]>

Lists configured remotes.

GitEngine.addRemote(repoPath: string, name: string, url: string): Promise<void>

Adds a remote.

GitEngine.removeRemote(repoPath: string, name: string): Promise<void>

Removes a remote.

GitEngine.setRemoteUrl(repoPath: string, name: string, url: string): Promise<void>

Updates a remote's URL.

Credentials

GitEngine.setCredential(repoId: string, credential: Credential): Promise<void>

Registers the credential the engine should use for a repo's remotes. Persists to expo-secure-store.

GitEngine.getCredential(repoId: string): Promise<NativeCredential | null>

Reads the currently registered credential.

GitEngine.clearCredential(repoId: string): Promise<void>

Removes the credential for a repo.

Other

GitEngine.repoInfo(repoPath: string): Promise<RepoInfo>

Returns repo metadata — path, branch, commit count, isClean.

GitEngine.backupCorruptRepo(repoPath: string): Promise<string>

Backs up a corrupt repo to a timestamped directory (never deletes). Used by reclone().

GitEngine.isBusy(repoPath: string): Promise<boolean>

Returns whether another op currently holds the flock for the repo.

GitEngine.version(): Promise<string>

Returns the native module version string.

GitEngine.engineName(): Promise<string>

Returns the engine name ('git2' when Rust module is active, 'stub' when unavailable).

Building the Rust Module

Build Script

File: scripts/build-rust.sh

--ios        Build for iOS (iOS device + simulator slices)
--android    Build for Android (arm64-v8a + armeabi-v7a)
--all        Build for all platforms
--bindings   Build only the JSI bindings (faster iteration)

Dependencies:

  • Rust toolchain (rustc, cargo)
  • cargo-lipo — for iOS fat library
  • cargo-ndk — for Android NDK

iOS Build

./scripts/build-rust.sh --ios

Outputs: modules/GitEngine/ios-local/rust/libgitnotes_git2.a (simulator) + modules/GitEngine/target/aarch64-apple-ios/release/libgitnotes_git2.a (device)

Android Build

./scripts/build-rust.sh --android

Outputs: modules/GitEngine/android/src/main/jniLibs/<abi>/libgitnotes_git2.so

Local Android Development

yarn android builds the Rust Android libraries before running expo run:android. The libraries are copied into the ignored modules/GitEngine/android/src/main/jniLibs/<abi>/ directories and packaged automatically by the GitEngine Android module. Run yarn build:rust:android directly when rebuilding the native libraries without launching the app.

Expo Autolinking

The module is linked via Expo's autolinking system. The package.json entry:

{
  "dependencies": {
    "gitnotes-git-engine": "file:./modules/GitEngine"
  }
}

Expo reads modules/GitEngine/package.json and links the native module automatically during prebuild.

Android Release Build (R8 / minification)

Release builds on Android use R8 minification (enabled via enableMinifyInReleaseBuilds: true in app.json under expo-build-properties). The GitEngine module depends on JNA 5.18.0 (net.java.dev.jna:jna:5.18.0@aar), and the UniFFI Kotlin bindings use JNA direct mapping through Native.register(...). R8 stripping JNA internals can make GitEngine unavailable at runtime, including errors such as Can't obtain peer field ID for class com.sun.jna.Pointer or Can't obtain static method fromNative(Class, Object) from class com.sun.jna.Native. The complete JNA Android keep rules are required:

-dontwarn java.awt.**
-dontwarn com.sun.jna.**
-keep class com.sun.jna.** { *; }
-keep class * extends com.sun.jna.** { *; }
-keepclassmembers class * extends com.sun.jna.** { public *; }

The rules are configured through expo-build-properties.extraProguardRules in app.json, so Expo prebuild regenerates them into android/app/proguard-rules.pro. Keeping the full JNA package also preserves the private reflection targets required by JNA's native initialization and the JNA types used by generated UniFFI bindings.

Android CA Store Configuration

GitHub HTTPS clones use TLS certificate verification. The vendored OpenSSL build in the Rust cdylib does not auto-detect Android's system CA certificate directories. On Android, git2's OpenSSL adapter must be explicitly pointed at the platform's CA store before any network operation.

How it works

The Kotlin GitEngineModule.OnCreate calls configureAndroidCaBundle() which:

  1. Checks for /apex/com.android.conscrypt/cacerts (Android 10+, preferred — Conscrypt APEX module).
  2. Falls back to /system/etc/security/cacerts (legacy path) only if the APEX path does not exist.
  3. If neither directory exists (not on Android), returns early — no configuration needed.
  4. Reads all readable regular files from the selected directory (Android CA files are named like 01419da9.0), sorted by name.
  5. For each file, extracts the -----BEGIN CERTIFICATE----- through -----END CERTIFICATE----- block (excluding any trailing Certificate: metadata and fingerprints that Android appends), appends a newline, and writes to the bundle.
  6. Concatenates them into a single PEM bundle file in app-private storage (filesDir/gitnotes_ca_bundle.pem), written atomically (temp file + rename).
  7. Skips rebuild if the bundle already exists and is non-empty.
  8. Fails silently (returns null, no configuration) if the bundle would be empty — no invalid bundle is passed to Rust.
  9. Passes the bundle path to setSslCertFile() — the UniFFI-exported set_ssl_cert_file(cert_file) in rust/src/api/bridge.rs.

Rust then calls git2::opts::set_ssl_cert_file with the bundle path, which configures libgit2's OpenSSL adapter to use the PEM bundle for certificate verification.

Why a PEM bundle instead of a directory?

libgit2 routes set_ssl_cert_dir to OpenSSL's SSL_CTX_load_verify_locations directory mode, which expects hash-named certificate files (e.g. a88126e5.0). Android uses this naming convention, but OpenSSL's directory-mode hash lookup is incompatible with Android's filesystem layout in this context. Using set_ssl_cert_file with a concatenated PEM bundle avoids this incompatibility.

Safety contract

git2::opts::set_ssl_cert_file calls into git_libgit2_opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, …) which mutates a C global (git__ssl_ctx) inside libgit2's OpenSSL adapter. This is process-global state, not thread-local. The function is therefore unsafe, and the Kotlin call site must satisfy these conditions:

  • The call runs once, on the main thread, before any async engine operations are dispatched.
  • No other thread can be inside a git2 call at the moment of invocation.

GitEngineModule.OnCreate satisfies both: it runs on the Android main thread during app startup, before the React Native JS thread has posted any engine work.

Certificate verification

No certificate bypass is involved. set_ssl_cert_file directs OpenSSL to the Android CA bundle; it does not disable verification. GitHub's TLS certificate remains validated against trusted system CAs.

Rust module: rust/src/engine/android_ca.rs 

// Errors from Android CA configuration.
pub enum AndroidCaError {
    SetCertFile(git2::Error),
    NotReadable(std::io::Error),
}

// Returns the best available Android CA certificate directory.
pub fn android_ca_dir(apex_override: Option<&Path>, legacy_override: Option<&Path>) -> Option<PathBuf>

// Configures git2's SSL CA file for Android.
// SAFETY: must be called from main thread before any git2 operations.
pub fn set_ssl_cert_file(cert_file: &Path) -> Result<(), AndroidCaError>

The #[uniffi::export] wrapper in rust/src/api/bridge.rs exposes set_ssl_cert_file as setSslCertFile(certFile: String) to Kotlin. The UniFFI layer maps AndroidCaError to BridgeError::Other, so Kotlin callers can catch BridgeException if the CA configuration fails.

Integration with JavaScript Services

The TypeScript facade at src/services/git/engine/GitEngine.ts is the single import point for all native Git operations. Services call it directly — there is no intermediate stub layer for real operations.

// CloneSyncService.save() — the actual clone-mode write path
import * as GitEngine from './git/engine/GitEngine';

await FileSystem.writeAsStringAsync(fullPath, content);
// The user stages and commits from the Git workspace or floating Git button.

Key integration points:

  • CloneSyncService.save() (src/services/cloneSyncServiceImpl.ts) — writes the file without staging it
  • CommitService or commitOps.ts — stages and creates explicit commits
  • ConflictResolverScreen — calls GitEngine.conflicts(), GitEngine.getConflictBlobs(), GitEngine.markConflictResolved()
  • BackgroundSyncService / ForegroundSyncService — call GitEngine.push() and GitEngine.pull()

Why Rust?

  • Performance: Git operations on large repos (thousands of files) are fast
  • Memory: Rust's zero-cost abstractions keep memory footprint low
  • Safety: No garbage collection pauses during sync operations
  • Portability: Rust compiles to iOS, Android, and desktop from the same codebase

See Also

Clone this wiki locally