Skip to content

Add git worktree support - #301

Closed
happycollision wants to merge 1 commit into
mainfrom
jaspr/main/ddd6546e
Closed

happycollision wants to merge 1 commit into
mainfrom
jaspr/main/ddd6546e

Conversation

@happycollision

@happycollision happycollision commented Dec 19, 2025 •

Copy link
Copy Markdown
Collaborator

I don't really know if this works because I needed to jump through hoops not represented in this commit to get things building on my machine. Buuuuut, maybe someone wants to test it out? 😄 I aimed Claude at it and guided the process somewhat, so I'd put my confidence level at a solid 20%.

Add git worktree support

This change enables git-jaspr to work from within git worktrees, which are
linked working directories that share a single repository. In a worktree,
.git is a file containing a gitdir: pointer rather than being a directory.

Problem

Previously, git-jaspr would fail when run from a worktree because:

  1. findNearestGitDir() in Cli.kt only checked for .git as a directory,
    failing to recognize worktrees where .git is a file.

  2. JGit's Git.open() doesn't support worktrees - it throws
    RepositoryNotFoundException when the .git is a file.

Solution

Cli.kt Changes

Added isGitWorkingDirectory() extension function that detects both:

  • Regular repositories: .git is a directory
  • Worktrees: .git is a file starting with gitdir:

Modified findNearestGitDir() to use this new function instead of only
checking isDirectory.

JGitClient.kt Changes

Added openRepository() function that handles worktrees by:

  1. Detecting if .git is a file (worktree indicator)
  2. Reading the gitdir: path to find the worktree's git directory
  3. Reading the commondir file to find the main repository's git directory
  4. Using FileRepositoryBuilder to construct a repository that:
    • Uses the worktree's working directory for file operations
    • Uses the main repository's git directory for refs and objects

Why Use the Main Repository's Git Directory?

JGit doesn't implement the commondir mechanism that git uses for worktrees.
In a worktree, the git directory structure is:

/main-repo/.git/                      # Main repository
/main-repo/.git/worktrees/foo/        # Worktree-specific: HEAD, index
/main-repo/.git/worktrees/foo/commondir  # Contains "../.." pointing to main
/main-repo/.git/refs/                 # Shared refs (all branches)
/main-repo/.git/objects/              # Shared objects (all commits)

/worktree-foo/.git                    # File containing "gitdir: /main-repo/.git/worktrees/foo"

When JGit opens the worktree's git directory directly, it can't resolve refs
because they're stored in the main repository's .git/refs/, not in the
worktree's .git/worktrees/foo/refs/.

By using the main repository's git directory with the worktree's working
directory, we get access to all refs and objects while file operations
(add, status) use the correct working directory.

Known Limitations

Due to JGit's incomplete worktree support:

  1. getCurrentBranchName() returns the main repository's current branch,
    not the worktree's branch. This is because HEAD is read from the main
    repository's git directory.

  2. Commits made via JGitClient go to the main repository's HEAD branch,
    not the worktree's checked-out branch.

These limitations are acceptable for git-jaspr because:

  • git-jaspr primarily uses CliGitClient for transport operations (fetch/push)
  • JGitClient is used for reading commits, refs, and repository state
  • The tool works with explicit ref names rather than relying on HEAD

Testing

Added comprehensive test suite in WorktreeSupportTest.kt (11 tests):

  • findNearestGitDir detection for regular repos and worktrees
  • findNearestGitDir from subdirectories within worktrees
  • isGitWorkingDirectory validation for various cases
  • JGitClient operations: log, logAll, commit, branch, refExists
  • Working directory cleanliness detection in worktrees

All worktree-specific tests pass. The 3 pre-existing test failures in
GitJasprDefaultTest are unrelated to these changes.

🤖 Generated with Claude Code

Stack:

⚠️ Part of a stack created by jaspr. Do not merge manually using the UI - doing so may have unexpected results.

This change enables git-jaspr to work from within git worktrees, which are
linked working directories that share a single repository. In a worktree,
`.git` is a file containing a `gitdir:` pointer rather than being a directory.

## Problem

Previously, git-jaspr would fail when run from a worktree because:

1. `findNearestGitDir()` in Cli.kt only checked for `.git` as a directory,
   failing to recognize worktrees where `.git` is a file.

2. JGit's `Git.open()` doesn't support worktrees - it throws
   `RepositoryNotFoundException` when the `.git` is a file.

## Solution

### Cli.kt Changes

Added `isGitWorkingDirectory()` extension function that detects both:
- Regular repositories: `.git` is a directory
- Worktrees: `.git` is a file starting with `gitdir:`

Modified `findNearestGitDir()` to use this new function instead of only
checking `isDirectory`.

### JGitClient.kt Changes

Added `openRepository()` function that handles worktrees by:

1. Detecting if `.git` is a file (worktree indicator)
2. Reading the `gitdir:` path to find the worktree's git directory
3. Reading the `commondir` file to find the main repository's git directory
4. Using `FileRepositoryBuilder` to construct a repository that:
   - Uses the worktree's working directory for file operations
   - Uses the main repository's git directory for refs and objects

### Why Use the Main Repository's Git Directory?

JGit doesn't implement the `commondir` mechanism that git uses for worktrees.
In a worktree, the git directory structure is:

```
/main-repo/.git/                      # Main repository
/main-repo/.git/worktrees/foo/        # Worktree-specific: HEAD, index
/main-repo/.git/worktrees/foo/commondir  # Contains "../.." pointing to main
/main-repo/.git/refs/                 # Shared refs (all branches)
/main-repo/.git/objects/              # Shared objects (all commits)

/worktree-foo/.git                    # File containing "gitdir: /main-repo/.git/worktrees/foo"
```

When JGit opens the worktree's git directory directly, it can't resolve refs
because they're stored in the main repository's `.git/refs/`, not in the
worktree's `.git/worktrees/foo/refs/`.

By using the main repository's git directory with the worktree's working
directory, we get access to all refs and objects while file operations
(add, status) use the correct working directory.

### Known Limitations

Due to JGit's incomplete worktree support:

1. `getCurrentBranchName()` returns the main repository's current branch,
   not the worktree's branch. This is because HEAD is read from the main
   repository's git directory.

2. Commits made via JGitClient go to the main repository's HEAD branch,
   not the worktree's checked-out branch.

These limitations are acceptable for git-jaspr because:
- git-jaspr primarily uses CliGitClient for transport operations (fetch/push)
- JGitClient is used for reading commits, refs, and repository state
- The tool works with explicit ref names rather than relying on HEAD

## Testing

Added comprehensive test suite in WorktreeSupportTest.kt (11 tests):

- `findNearestGitDir` detection for regular repos and worktrees
- `findNearestGitDir` from subdirectories within worktrees
- `isGitWorkingDirectory` validation for various cases
- JGitClient operations: log, logAll, commit, branch, refExists
- Working directory cleanliness detection in worktrees

All worktree-specific tests pass. The 3 pre-existing test failures in
GitJasprDefaultTest are unrelated to these changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
commit-id: ddd6546e
@MichaelSims

Copy link
Copy Markdown
Owner

Merged in another commit, thank you

@MichaelSims
MichaelSims deleted the jaspr/main/ddd6546e branch December 27, 2025 14:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants