git-chopstick-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 git-chopstick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# git-chopstick-core
+
+A standalone Git backend library extracted from [GitHub Desktop](https://github.com/desktop/desktop). Provides TypeScript-first wrappers around the Git CLI for repository operations.
+
+## Features
+
+- **60+ Git command wrappers** — status, diff, log, branch, commit, merge, rebase, stash, worktree, fetch, push, pull, cherry-pick, and more
+- **Full dugite replacement** — `exec.ts` uses direct `child_process.spawn('git', ...)` instead of the dugite npm package
+- **Pure CLI-based** — works with the user's installed Git, no native bindings
+- **TypeScript-first** — complete type definitions for all Git models and operations
+- **Zero Electron dependencies** — can be used in Node.js or Bun
+
+## Usage
+
+### As a local dependency
+
+```typescript
+import { Repository } from 'git-chopstick-core/src/models/repository.js'
+import { getStatus } from 'git-chopstick-core/src/git/status.js'
+
+const repo = new Repository('/path/to/repo', 1)
+const status = await getStatus(repo)
+
+console.log(`Branch: ${status.currentBranch}`)
+console.log(`Changed files: ${status.workingDirectory.files.length}`)
+```
+
+Install via `file:` dependency in your `package.json`:
+```json
+{
+  "dependencies": {
+    "git-chopstick-core": "file:../path/to/git-core"
+  }
+}
+```
+
+### From within this repo
+
+```bash
+npx tsx examples/get-status.ts /path/to/repo
+```
+
+## Architecture
+
+The library is structured into three layers:
+
+| Layer | Directory | Purpose |
+|-------|-----------|---------|
+| **Git commands** | `src/git/` | 61 files wrapping individual `git` subcommands — `status.ts`, `log.ts`, `diff.ts`, `branch.ts`, `merge.ts`, etc. |
+| **Domain models** | `src/models/` | 19 type definition files — `Commit`, `Branch`, `Repository`, `IStatusResult`, diff types, etc. |
+| **Utilities** | `src/lib/` | 25 files — diff parser, status parser, progress reporting stubs, trampoline, hooks, etc. |
+
+### Key file: `src/git/exec.ts`
+
+This is the core dugite replacement (~250 lines). It implements:
+- `exec()` — spawns `git` via `child_process.spawn`, returns `{ stdout, stderr, exitCode }`
+- `spawnGit()` — stream-based variant for long-running operations
+- `GitError` enum — 50+ typed Git error codes
+- `parseError()` — maps stderr output to typed errors
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `byline` | Line-by-line stream reading |
+| `ignore` | `.gitignore` pattern matching |
+| `memoize-one` | Memoization for remote fetching |
+
+## License
+
+MIT — extracted from [GitHub Desktop](https://github.com/desktop/desktop) (MIT licensed).

package/examples/get-status.ts

@@ -0,0 +1,84 @@
+/**
+ * Example: Open a repo and show its current status.
+ *
+ * Usage:
+ *   bun examples/get-status.ts /path/to/some/repo
+ */
+
+import { Repository } from '../src/models/repository'
+import { getStatus } from '../src/git/status'
+
+async function main() {
+  const repoPath = process.argv[2]
+  if (!repoPath) {
+    console.error('Usage: bun examples/get-status.ts <path-to-repo>')
+    process.exit(1)
+  }
+
+  const repo = new Repository(repoPath, 1)
+
+  console.log(`\n📂 Repository: ${repo.name}`)
+  console.log(`   Path: ${repo.path}\n`)
+
+  const status = await getStatus(repo)
+
+  if (!status) {
+    console.log('❌ Could not read repository status (not a git repo?)')
+    process.exit(1)
+  }
+
+  // Branch info
+  console.log(`🌿 Branch: ${status.currentBranch ?? '(detached HEAD)'}`)
+  if (status.currentUpstreamBranch) {
+    console.log(`   Upstream: ${status.currentUpstreamBranch}`)
+  }
+  if (status.branchAheadBehind) {
+    const { ahead, behind } = status.branchAheadBehind
+    console.log(`   Ahead: ${ahead}  |  Behind: ${behind}`)
+  }
+  console.log(`   Tip: ${status.currentTip?.slice(0, 7) ?? 'N/A'}`)
+
+  // Conflicted files
+  if (status.doConflictedFilesExist) {
+    console.log(`\n⚠️  Conflicts detected!`)
+  }
+
+  // Working directory changes
+  const files = status.workingDirectory.files
+  console.log(`\n📝 Changed files: ${files.length}`)
+
+  // Group by status kind
+  const byKind = new Map<string, string[]>()
+  for (const file of files) {
+    const kind = file.status.kind
+    const list = byKind.get(kind) ?? []
+    list.push(file.status.kind === 'Renamed' || file.status.kind === 'Copied'
+      ? `${file.path} (was: ${file.status.oldPath})`
+      : file.path)
+    byKind.set(kind, list)
+  }
+
+  for (const [kind, paths] of byKind) {
+    console.log(`   ${kind}:`)
+    for (const p of paths) {
+      console.log(`     - ${p}`)
+    }
+  }
+
+  // Merge/rebase state
+  if (status.mergeHeadFound) {
+    console.log(`\n🔀 Merge in progress`)
+  }
+  if (status.rebaseInternalState) {
+    console.log(`\n🔄 Rebase in progress`)
+    console.log(`   Target: ${status.rebaseInternalState.targetBranch}`)
+  }
+  if (status.isCherryPickingHeadFound) {
+    console.log(`\n🍒 Cherry-pick in progress`)
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "git-chopstick-core",
+  "version": "0.1.0",
+  
+  "type": "module",
+  "description": "Git backend library extracted from GitHub Desktop",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "byline": "^5.0.0",
+    "ignore": "^7.0.5",
+    "memoize-one": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/byline": "^4.2.36",
+    "@types/node": "^22.19.20",
+    "typescript": "^5.9.3"
+  }
+}

package/src/git/add.ts

@@ -0,0 +1,16 @@
+import { git } from './core'
+import { Repository } from '../models/repository'
+import { WorkingDirectoryFileChange } from '../models/status'
+
+/**
+ * Add a conflicted file to the index.
+ *
+ * Typically done after having resolved conflicts either manually
+ * or through checkout --theirs/--ours.
+ */
+export async function addConflictedFile(
+  repository: Repository,
+  file: WorkingDirectoryFileChange
+) {
+  await git(['add', '--', file.path], repository.path, 'addConflictedFile')
+}

package/src/git/apply.ts

@@ -0,0 +1,154 @@
+import { GitError as DugiteError } from './exec'
+import { git } from './core'
+import {
+  WorkingDirectoryFileChange,
+  AppFileStatusKind,
+} from '../models/status'
+import { DiffType, ITextDiff, DiffSelection } from '../models/diff'
+import { Repository } from '../models/repository'
+import { getWorkingDirectoryDiff } from './diff'
+import { formatPatch, formatPatchToDiscardChanges } from '../lib/patch-formatter'
+import { assertNever } from '../lib/fatal-error'
+
+export async function applyPatchToIndex(
+  repository: Repository,
+  file: WorkingDirectoryFileChange
+): Promise<void> {
+  // If the file was a rename we have to recreate that rename since we've
+  // just blown away the index. Think of this block of weird looking commands
+  // as running `git mv`.
+  if (file.status.kind === AppFileStatusKind.Renamed) {
+    // Make sure the index knows of the removed file. We could use
+    // update-index --force-remove here but we're not since it's
+    // possible that someone staged a rename and then recreated the
+    // original file and we don't have any guarantees for in which order
+    // partial stages vs full-file stages happen. By using git add the
+    // worst that could happen is that we re-stage a file already staged
+    // by updateIndex.
+    await git(
+      ['add', '--update', '--', file.status.oldPath],
+      repository.path,
+      'applyPatchToIndex'
+    )
+
+    // Figure out the blob oid of the removed file
+    // <mode> SP <type> SP <object> TAB <file>
+    const oldFile = await git(
+      ['ls-tree', 'HEAD', '--', file.status.oldPath],
+      repository.path,
+      'applyPatchToIndex'
+    )
+
+    const [info] = oldFile.stdout.split('\t', 1)
+    const [mode, , oid] = info.split(' ', 3)
+
+    // Add the old file blob to the index under the new name
+    await git(
+      ['update-index', '--add', '--cacheinfo', mode, oid, file.path],
+      repository.path,
+      'applyPatchToIndex'
+    )
+  }
+
+  const applyArgs: string[] = [
+    'apply',
+    '--cached',
+    '--unidiff-zero',
+    '--whitespace=nowarn',
+    '-',
+  ]
+
+  const diff = await getWorkingDirectoryDiff(repository, file)
+
+  if (diff.kind !== DiffType.Text && diff.kind !== DiffType.LargeText) {
+    const { kind } = diff
+    switch (diff.kind) {
+      case DiffType.Binary:
+      case DiffType.Submodule:
+      case DiffType.Image:
+        throw new Error(
+          `Can't create partial commit in binary file: ${file.path}`
+        )
+      case DiffType.Unrenderable:
+        throw new Error(
+          `File diff is too large to generate a partial commit: ${file.path}`
+        )
+      default:
+        assertNever(diff, `Unknown diff kind: ${kind}`)
+    }
+  }
+
+  const patch = await formatPatch(repository, file, file.selection)
+  await git(applyArgs, repository.path, 'applyPatchToIndex', { stdin: patch })
+
+  return Promise.resolve()
+}
+
+/**
+ * Test a patch to see if it will apply cleanly.
+ *
+ * @param workTree work tree (which should be checked out to a specific commit)
+ * @param patch a Git patch (or patch series) to try applying
+ * @returns whether the patch applies cleanly
+ *
+ * See `formatPatch` to generate a patch series from existing Git commits
+ */
+export async function checkPatch(
+  workTree: { path: string },
+  patch: string
+): Promise<boolean> {
+  const result = await git(
+    ['apply', '--check', '-'],
+    workTree.path,
+    'checkPatch',
+    {
+      stdin: patch,
+      encoding: 'utf8' as any,
+      expectedErrors: new Set<DugiteError>([DugiteError.PatchDoesNotApply]),
+    }
+  )
+
+  if (result.gitError === DugiteError.PatchDoesNotApply) {
+    // other errors will be thrown if encountered, so this is fine for now
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Discards the local changes for the specified file based on the passed diff
+ * and a selection of lines from it.
+ *
+ * When passed an empty selection, this method won't do anything. When passed a
+ * full selection, all changes from the file will be discarded.
+ *
+ * @param repository The repository in which to update the working directory
+ *                   with information from the index
+ *
+ * @param filePath   The relative path in the working directory of the file to use
+ *
+ * @param diff       The diff containing the file local changes
+ *
+ * @param selection  The selection of changes from the diff to discard
+ */
+export async function discardChangesFromSelection(
+  repository: Repository,
+  filePath: string,
+  diff: ITextDiff,
+  selection: DiffSelection
+) {
+  const file = new WorkingDirectoryFileChange(filePath, { kind: AppFileStatusKind.Modified }, selection)
+  const patch = await formatPatchToDiscardChanges(repository, file)
+
+  if (patch === null || patch === '') {
+    // When the patch is null we don't need to apply it since it will be a noop.
+    return
+  }
+
+  const args = ['apply', '--unidiff-zero', '--whitespace=nowarn', '-']
+
+  await git(args, repository.path, 'discardChangesFromSelection', {
+    stdin: patch,
+  })
+}

package/src/git/authentication.ts

@@ -0,0 +1,19 @@
+import { GitError as DugiteError } from './exec'
+
+/** Get the environment for authenticating remote operations. */
+export function envForAuthentication(): Record<string, string | undefined> {
+  return {
+    // supported since Git 2.3, this is used to ensure we never interactively prompt
+    // for credentials - even as a fallback
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_TRACE: localStorage.getItem('git-trace') || '0',
+  }
+}
+
+/** The set of errors which fit under the "authentication failed" umbrella. */
+export const AuthenticationErrors: ReadonlySet<DugiteError> = new Set([
+  DugiteError.HTTPSAuthenticationFailed,
+  DugiteError.SSHAuthenticationFailed,
+  DugiteError.HTTPSRepositoryNotFound,
+  DugiteError.SSHRepositoryNotFound,
+])

package/src/git/branch.ts

@@ -0,0 +1,206 @@
+import { git, isGitError } from './core'
+import { Repository } from '../models/repository'
+import { Branch } from '../models/branch'
+import { formatAsLocalRef } from './refs'
+import { deleteRef } from './update-ref'
+import { GitError as DugiteError } from './exec'
+import { envForRemoteOperation } from './environment'
+import { createForEachRefParser } from './git-delimiter-parser'
+import { IRemote } from '../models/remote'
+import { coerceToString } from './coerce-to-string'
+
+/**
+ * Create a new branch from the given start point.
+ *
+ * @param repository - The repository in which to create the new branch
+ * @param name       - The name of the new branch
+ * @param startPoint - A committish string that the new branch should be based
+ *                     on, or undefined if the branch should be created based
+ *                     off of the current state of HEAD
+ */
+export async function createBranch(
+  repository: Repository,
+  name: string,
+  startPoint: string | null,
+  noTrack?: boolean
+): Promise<void> {
+  const args =
+    startPoint !== null ? ['branch', name, startPoint] : ['branch', name]
+
+  // if we're branching directly from a remote branch, we don't want to track it
+  // tracking it will make the rest of desktop think we want to push to that
+  // remote branch's upstream (which would likely be the upstream of the fork)
+  if (noTrack) {
+    args.push('--no-track')
+  }
+
+  await git(args, repository.path, 'createBranch')
+}
+
+export const getBranchNames = ({ path }: Repository): Promise<string[]> => {
+  const parser = createForEachRefParser({ name: '%(refname:short)' })
+  return git(['branch', ...parser.formatArgs], path, 'getBranchNames').then(x =>
+    parser.parse(x.stdout).map(b => b.name)
+  )
+}
+
+/** Rename the given branch to a new name. */
+export async function renameBranch(
+  repository: Repository,
+  branch: Branch,
+  newName: string,
+  force?: boolean
+): Promise<void> {
+  try {
+    await git(
+      ['branch', force ? '-M' : '-m', branch.nameWithoutRemote, newName],
+      repository.path,
+      'renameBranch'
+    )
+  } catch (error) {
+    // If we failed to rename and the branch name only differs by case, we
+    // we'll try again with the -M flag to force the rename. See
+    // https://github.com/desktop/desktop/issues/21320
+    if (
+      // Only retry if the caller hasn't explicitly asked us to force the rename
+      force === undefined &&
+      isGitError(error) &&
+      error.result.gitError === DugiteError.BranchAlreadyExists
+    ) {
+      const stderr = coerceToString(error.result.stderr)
+      const m = /fatal: a branch named '(.+?)' already exists/.exec(stderr)
+
+      if (m && m[1].toLowerCase() === newName.toLowerCase()) {
+        // At this point we're almost certain that we are dealing with a
+        // case-only rename on a case insensitive filesystem, but we can't
+        // be 100% sure, NTFS can be configured to be case sensitive and macOS
+        // might have case sensitive file systems mounted so we have to list
+        // all branches and check the names.
+        return (
+          getBranchNames(repository)
+            // Throw the original error if we fail to get the branch names
+            .catch(() => Promise.reject(error))
+            .then(names =>
+              // If we find the new name in the list of branches we can't
+              // safely assume it's a case-only rename and have to
+              // propagate the original error, otherwise try again with -M
+              names.includes(newName)
+                ? Promise.reject(error)
+                : renameBranch(repository, branch, newName, true)
+            )
+        )
+      }
+    }
+    throw error
+  }
+}
+
+/**
+ * Delete the branch locally.
+ */
+export async function deleteLocalBranch(
+  repository: Repository,
+  branchName: string
+): Promise<true> {
+  await git(['branch', '-D', branchName], repository.path, 'deleteLocalBranch')
+  return true
+}
+
+/**
+ * Deletes a remote branch
+ *
+ * @param remoteName - the name of the remote to delete the branch from
+ * @param remoteBranchName - the name of the branch on the remote
+ */
+export async function deleteRemoteBranch(
+  repository: Repository,
+  remote: IRemote,
+  remoteBranchName: string
+): Promise<true> {
+  const args = ['push', remote.name, `:${remoteBranchName}`]
+
+  // If the user is not authenticated, the push is going to fail
+  // Let this propagate and leave it to the caller to handle
+  const result = await git(args, repository.path, 'deleteRemoteBranch', {
+    env: await envForRemoteOperation(remote.url),
+    expectedErrors: new Set<DugiteError>([DugiteError.BranchDeletionFailed]),
+  })
+
+  // It's possible that the delete failed because the ref has already
+  // been deleted on the remote. If we identify that specific
+  // error we can safely remove our remote ref which is what would
+  // happen if the push didn't fail.
+  if (result.gitError === DugiteError.BranchDeletionFailed) {
+    const ref = `refs/remotes/${remote.name}/${remoteBranchName}`
+    await deleteRef(repository, ref)
+  }
+
+  return true
+}
+
+/**
+ * Finds branches that have a tip equal to the given committish
+ *
+ * @param repository within which to execute the command
+ * @param commitish a sha, HEAD, etc that the branch(es) tip should be
+ * @returns list branch names. null if an error is encountered
+ */
+export async function getBranchesPointedAt(
+  repository: Repository,
+  commitish: string
+): Promise<Array<string> | null> {
+  const args = [
+    'branch',
+    `--points-at=${commitish}`,
+    '--format=%(refname:short)',
+  ]
+  // this command has an implicit \n delimiter
+  const { stdout, exitCode } = await git(
+    args,
+    repository.path,
+    'branchPointedAt',
+    {
+      // - 1 is returned if a common ancestor cannot be resolved
+      // - 129 is returned if ref is malformed
+      //   "warning: ignoring broken ref refs/remotes/origin/main."
+      successExitCodes: new Set([0, 1, 129]),
+    }
+  )
+  if (exitCode === 1 || exitCode === 129) {
+    return null
+  }
+  // split (and remove trailing element cause its always an empty string)
+  return stdout.split('\n').slice(0, -1)
+}
+
+/**
+ * Gets all branches that have been merged into the given branch
+ *
+ * @param repository The repository in which to search
+ * @param branchName The to be used as the base branch
+ * @returns map of branch canonical refs paired to its sha
+ */
+export async function getMergedBranches(
+  repository: Repository,
+  branchName: string
+): Promise<Map<string, string>> {
+  const canonicalBranchRef = formatAsLocalRef(branchName)
+  const { formatArgs, parse } = createForEachRefParser({
+    sha: '%(objectname)',
+    canonicalRef: '%(refname)',
+  })
+
+  const args = ['branch', ...formatArgs, '--merged', branchName]
+  const mergedBranches = new Map<string, string>()
+  const { stdout } = await git(args, repository.path, 'mergedBranches')
+
+  for (const branch of parse(stdout)) {
+    // Don't include the branch we're using to compare against
+    // in the list of branches merged into that branch.
+    if (branch.canonicalRef !== canonicalBranchRef) {
+      mergedBranches.set(branch.canonicalRef, branch.sha)
+    }
+  }
+
+  return mergedBranches
+}

package/src/git/checkout-index.ts

@@ -0,0 +1,40 @@
+import { git } from './core'
+import { Repository } from '../models/repository'
+
+/**
+ * Forcefully updates the working directory with information from the index
+ * for a given set of files.
+ *
+ * This method is essentially the same as running `git checkout -- files`
+ * except by using `checkout-index` we can pass the files we want updated
+ * on stdin, avoiding all issues with too long arguments.
+ *
+ * Note that this function will not yield errors for paths that don't
+ * exist in the index (-q).
+ *
+ * @param repository The repository in which to update the working directory
+ *                   with information from the index
+ *
+ * @param paths      The relative paths in the working directory to update
+ *                   with information from the index.
+ */
+export async function checkoutIndex(
+  repository: Repository,
+  paths: ReadonlyArray<string>
+) {
+  if (!paths.length) {
+    return
+  }
+
+  const options = {
+    successExitCodes: new Set([0, 1]),
+    stdin: paths.join('\0'),
+  }
+
+  await git(
+    ['checkout-index', '-f', '-u', '-q', '--stdin', '-z'],
+    repository.path,
+    'checkoutIndex',
+    options
+  )
+}