Walkthrough

Adds cherry-pick support: new public cherryPick API and internal _cherryPick command implementing three‑way merge, new CherryPickMergeCommitError and CherryPickRootCommitError, updated exports, extensive tests (including submodule cases), and contributor/README updates.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant API as cherryPick API
    participant Cmd as _cherryPick Command
    participant Git as Git Ops
    participant Merger as mergeTree
    participant Index as Index/Worktree Manager

    User->>API: cherryPick({ oid, options })
    API->>API: validate params / normalize committer
    API->>Cmd: _cherryPick({ oid, options })

    Cmd->>Git: readCommit(oid)
    Git-->>Cmd: commitObj
    Cmd->>Git: readCommit(HEAD)
    Git-->>Cmd: headCommit
    Cmd->>Git: readCommit(parent of oid)
    Git-->>Cmd: baseCommit

    Cmd->>Merger: mergeTree(our=HEAD.tree, base=base.tree, their=oid.tree, mergeDriver)
    Merger-->>Cmd: mergedTree or MergeConflictError

    alt MergeConflictError & abortOnConflict
        Cmd-->>API: throw MergeConflictError
    else Conflicts handled / merged
        Cmd->>Git: commit(tree=mergedTree, parent=HEAD, author=orig, committer=new)
        Git-->>Cmd: newOid
        Cmd->>Index: applyTreeChanges(newOid) (unless dryRun/noUpdateBranch)
        Index-->>Cmd: index/worktree updated
        Cmd-->>API: return newOid
    end
    API-->>User: newOid or error

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~65 minutes

Poem

🐰 I hopped through trees to pick a patch,
Three branches met and made a match,
Commits replayed with careful cheer,
Conflicts checked — no need to fear,
Backports bloom, a carrot batch! 🍒

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• 📝 Generate docstrings

__tests__/test-cherryPick-in-submodule.js (2)

24-164: Extract repeated submodule setup into a helper function.

Every test case repeats ~30-40 lines of identical submodule scaffolding (create superproject fixture, _mkdir, _cp, write .git file, init, setConfig). This makes each test harder to read and maintain — a single change to the setup pattern requires editing all 8 tests.

Consider extracting a helper like:

async function setupSubmoduleRepo(fixtureName, moduleName, opts = {}) {
  const { fs: fssp, dir: dirsp } = await makeFixture('superproject-test')
  const { dir, gitdir } = await makeFixture(fixtureName)
  await fssp._mkdir(join(dirsp, '.git'))
  await fssp._mkdir(join(dirsp, '.git', 'modules'))
  const gitdirsmfullpath = join(dirsp, '.git', 'modules', moduleName)
  await fssp._cp(gitdir, gitdirsmfullpath, { recursive: true })
  const officialSubmoduleDir = join(dirsp, moduleName)
  await fssp._cp(dir, officialSubmoduleDir, { recursive: true })
  const submoduleGitFile = join(officialSubmoduleDir, '.git')
  await fssp._writeFile(
    submoduleGitFile,
    `gitdir: ../.git/modules/${moduleName}\n`
  )
  await init({ fs: fssp, dir: officialSubmoduleDir, gitdir: submoduleGitFile })
  if (opts.setCommitter !== false) {
    await setConfig({ fs: fssp, dir: officialSubmoduleDir, gitdir: submoduleGitFile, path: 'user.name', value: opts.committerName || 'Committer' })
    await setConfig({ fs: fssp, dir: officialSubmoduleDir, gitdir: submoduleGitFile, path: 'user.email', value: opts.committerEmail || '[email protected]' })
  }
  return { fs: fssp, dir: officialSubmoduleDir, gitdir: submoduleGitFile }
}

This would reduce each test to its unique logic and make the suite much more maintainable.

---

726-790: Root commit test: gitCommit relies on config rather than explicit author — verify this is intentional.

At Line 768, gitCommit is called without an explicit author parameter, unlike all other tests in this file which pass author explicitly. It relies on user.name/user.email from setConfig (Lines 746-758). This works, but the implicit behavior differs from the rest of the test suite.

If intentional (testing that cherry-pick works with config-derived authors), a brief comment would help. Otherwise, pass author explicitly for consistency.

__tests__/test-cherryPick.js (1)

199-202: Redundant checkout on Line 200.

At this point, the test is already on branch b (checked out at Line 194). The checkout at Line 200 is a no-op.

Proposed fix

     await gitCommit({ fs, dir, gitdir, message: 'b' })
 
     // Merge a into b to create a merge commit on b
-    await checkout({ fs, dir, gitdir, ref: 'b' })
-    // Use merge API to create a merge commit
     await merge({ fs, dir, gitdir, theirs: 'a' })

• X
• Mastodon
• Reddit
• LinkedIn