@jasonfutch/worktree-manager 1.0.0 → 1.1.0

package/README.md

@@ -6,6 +6,7 @@ A terminal app for managing git worktrees with AI assistance.
 
 - **TUI Interface** - Full terminal UI built with blessed
 - **Git Worktree Management** - Create, list, and remove worktrees
+- **Branch Flexibility** - Create worktrees from new branches, existing local branches, or remote branches
 - **IDE Integration** - Open worktrees in VS Code, Cursor, Zed, and more
 - **AI Integration** - Launch Claude, Gemini, or Codex in any worktree
 - **Parallel Development** - Work on multiple features simultaneously
@@ -42,7 +43,7 @@ wtm /path/to/repo
 | `↑/k`   | Move up                   |
 | `↓/j`   | Move down                 |
 | `Enter` | Select/Details            |
-| `n`     | Create new worktree       |
+| `n`     | Create worktree (new or existing branch) |
 | `d`     | Delete worktree           |
 | `e`     | Open in editor (selector) |
 | `t`     | Open terminal             |
@@ -51,6 +52,19 @@ wtm /path/to/repo
 | `?`     | Help                      |
 | `q`     | Quit                      |
 
+### Creating Worktrees
+
+Press `n` to create a new worktree. You'll be presented with two options:
+
+1. **Create new branch** - Enter a new branch name and select a base branch to create it from
+2. **Use existing branch** - Select from available local or remote branches
+
+When using existing branches:
+- Local branches are listed first
+- Remote branches are marked with ⬇ and listed after local branches
+- Selecting a remote branch (e.g., `origin/feature`) automatically creates a local tracking branch
+- Branches already checked out in other worktrees are filtered out
+
 ### CLI Commands
 
 ```bash
@@ -58,11 +72,15 @@ wtm /path/to/repo
 wtm list
 wtm list /path/to/repo
 
-# Create a new worktree
+# Create a new worktree (creates new branch from base)
 wtm create feature/my-feature
 wtm create feature/my-feature -b main
 wtm create feature/my-feature -p /custom/path
 
+# Create worktree from existing branch
+wtm create existing-branch        # Uses existing local branch
+wtm create origin/feature -e      # Creates local tracking branch from remote
+
 # Remove a worktree
 wtm remove feature/my-feature
 wtm remove feature/my-feature --force

package/dist/git/worktree.d.ts

@@ -1,4 +1,4 @@
-import type { Worktree, CreateWorktreeOptions } from '../types.js';
+import type { Worktree, CreateWorktreeOptions, BranchInfo } from '../types.js';
 export declare class GitWorktree {
     private repoPath;
     constructor(repoPath: string);
@@ -44,6 +44,11 @@ export declare class GitWorktree {
      * @note This method returns empty array on any error
      */
     getBranches(): Promise<string[]>;
+    /**
+     * Get all branches (local and remote) with structured info
+     * @returns Array of BranchInfo objects, empty array on error
+     */
+    getAllBranches(): Promise<BranchInfo[]>;
     /**
      * Get current branch name
      * @returns Current branch name, or 'unknown' on error

package/dist/git/worktree.js

@@ -110,13 +110,16 @@ export class GitWorktree {
      * Create a new worktree
      */
     async create(options) {
-        const { branch, baseBranch = GIT.DEFAULT_BASE_BRANCH, path: customPath } = options;
-        // Validate branch name
-        if (!isValidBranchName(branch)) {
-            throw new InvalidBranchError(branch, 'Branch names cannot contain spaces, .., or special characters');
+        const { branch, baseBranch = GIT.DEFAULT_BASE_BRANCH, path: customPath, useExisting = false } = options;
+        // For existing branches, the branch might be a remote ref like 'origin/feature'
+        const isRemoteBranch = branch.includes('/') && !branch.startsWith('refs/');
+        const localBranchName = isRemoteBranch ? branch.split('/').slice(1).join('/') : branch;
+        // Validate branch name (use local name for validation)
+        if (!isValidBranchName(localBranchName)) {
+            throw new InvalidBranchError(localBranchName, 'Branch names cannot contain spaces, .., or special characters');
         }
         // Generate worktree path if not provided
-        const worktreePath = customPath || path.join(path.dirname(this.repoPath), GIT.WORKTREES_DIR, branch.replace(/\//g, '-'));
+        const worktreePath = customPath || path.join(path.dirname(this.repoPath), GIT.WORKTREES_DIR, localBranchName.replace(/\//g, '-'));
         // Validate path doesn't contain traversal attempts
         const repoParent = path.dirname(this.repoPath);
         if (!isPathSafe(worktreePath, repoParent)) {
@@ -128,20 +131,42 @@ export class GitWorktree {
             fs.mkdirSync(parentDir, { recursive: true });
         }
         try {
-            // Check if branch exists
-            const branchExists = await this.branchExists(branch);
             // Use escaped arguments for safety
             const escapedPath = escapeShellArg(worktreePath);
-            const escapedBranch = escapeShellArg(branch);
+            const escapedLocalBranch = escapeShellArg(localBranchName);
             const escapedBase = escapeShellArg(baseBranch);
             let command;
-            if (branchExists) {
-                // Checkout existing branch
-                command = `git worktree add ${escapedPath} ${escapedBranch}`;
+            if (useExisting) {
+                if (isRemoteBranch) {
+                    // For remote branches, create a local tracking branch
+                    const escapedRemoteBranch = escapeShellArg(branch);
+                    // Check if a local branch with this name already exists
+                    const localExists = await this.branchExists(localBranchName);
+                    if (localExists) {
+                        // Use the existing local branch
+                        command = `git worktree add ${escapedPath} ${escapedLocalBranch}`;
+                    }
+                    else {
+                        // Create a new local branch tracking the remote
+                        command = `git worktree add -b ${escapedLocalBranch} ${escapedPath} ${escapedRemoteBranch}`;
+                    }
+                }
+                else {
+                    // For local branches, just check them out
+                    command = `git worktree add ${escapedPath} ${escapedLocalBranch}`;
+                }
             }
             else {
-                // Create new branch from base
-                command = `git worktree add -b ${escapedBranch} ${escapedPath} ${escapedBase}`;
+                // Creating a new branch
+                const branchExists = await this.branchExists(branch);
+                if (branchExists) {
+                    // Branch already exists, just check it out
+                    command = `git worktree add ${escapedPath} ${escapedLocalBranch}`;
+                }
+                else {
+                    // Create new branch from base
+                    command = `git worktree add -b ${escapedLocalBranch} ${escapedPath} ${escapedBase}`;
+                }
             }
             await execAsync(command, { cwd: this.repoPath });
             // Get the created worktree info
@@ -247,6 +272,66 @@ export class GitWorktree {
             return [];
         }
     }
+    /**
+     * Get all branches (local and remote) with structured info
+     * @returns Array of BranchInfo objects, empty array on error
+     */
+    async getAllBranches() {
+        try {
+            // Fetch remote refs first to ensure we have the latest
+            await execAsync('git fetch --all --prune', { cwd: this.repoPath }).catch(() => {
+                // Ignore fetch errors (e.g., no network)
+            });
+            const { stdout } = await execAsync('git branch -a --format="%(refname:short)"', {
+                cwd: this.repoPath
+            });
+            const branches = [];
+            const lines = stdout.trim().split('\n').filter(b => b);
+            // Get list of branches already checked out in worktrees
+            const worktrees = await this.list();
+            const checkedOutBranches = new Set(worktrees.map(wt => wt.branch).filter(b => b !== 'HEAD (detached)'));
+            for (const line of lines) {
+                // Skip HEAD pointer
+                if (line === 'HEAD' || line.includes('->'))
+                    continue;
+                if (line.startsWith('origin/')) {
+                    // Remote branch
+                    const remoteName = 'origin';
+                    const branchName = line.substring(7); // Remove 'origin/' prefix
+                    // Skip if this remote branch is already checked out locally
+                    if (checkedOutBranches.has(branchName))
+                        continue;
+                    branches.push({
+                        name: branchName,
+                        fullName: line,
+                        isRemote: true,
+                        remote: remoteName
+                    });
+                }
+                else {
+                    // Local branch - skip if already checked out in a worktree
+                    if (checkedOutBranches.has(line))
+                        continue;
+                    branches.push({
+                        name: line,
+                        fullName: line,
+                        isRemote: false
+                    });
+                }
+            }
+            // Sort: local branches first, then remote, alphabetically within each group
+            branches.sort((a, b) => {
+                if (a.isRemote !== b.isRemote) {
+                    return a.isRemote ? 1 : -1;
+                }
+                return a.name.localeCompare(b.name);
+            });
+            return branches;
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Get current branch name
      * @returns Current branch name, or 'unknown' on error

package/dist/index.js

@@ -93,6 +93,7 @@ program
     .argument('[path]', 'Path to git repository', '.')
     .option('-b, --base <branch>', 'Base branch to create from', 'main')
     .option('-p, --path <path>', 'Custom path for the worktree')
+    .option('-e, --existing', 'Use existing branch (local or remote)')
     .action(async (branch, repoPath, options) => {
     const resolvedPath = path.resolve(repoPath || '.');
     const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
@@ -101,12 +102,18 @@ program
         process.exit(1);
     }
     const git = new GitWorktree(repoRoot);
-    console.log(chalk.cyan(`Creating worktree for branch: ${branch}...`));
+    const isRemote = branch.includes('/') && !branch.startsWith('refs/');
+    const displayBranch = isRemote ? branch : branch;
+    const message = options.existing && isRemote
+        ? `Creating worktree from ${displayBranch} (will create local tracking branch)...`
+        : `Creating worktree for branch: ${displayBranch}...`;
+    console.log(chalk.cyan(message));
     try {
         const wt = await git.create({
             branch,
             baseBranch: options.base,
-            path: options.path
+            path: options.path,
+            useExisting: options.existing
         });
         console.log(chalk.green(`✓ Created worktree: ${wt.path}`));
     }
@@ -257,11 +264,12 @@ ${chalk.yellow.bold('CLI COMMANDS')}
     $ wtm list
     $ wtm list /path/to/repo
 
-  ${chalk.cyan('wtm create')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-b base] [-p path]')}
+  ${chalk.cyan('wtm create')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-b base] [-p path] [-e]')}
     Create a new worktree
     $ wtm create feature/login
     $ wtm create feature/api -b develop
     $ wtm create bugfix/issue-42 -p /custom/path
+    $ wtm create origin/feature -e  ${chalk.gray('# Use existing remote branch')}
 
   ${chalk.cyan('wtm remove')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-f]')}
     Remove a worktree

package/dist/tui/app.d.ts

@@ -26,6 +26,8 @@ export declare class WorktreeManagerTUI {
     private isProtectedBranch;
     private showHelp;
     private promptCreateWorktree;
+    private promptCreateNewBranch;
+    private promptUseExistingBranch;
     private promptDeleteWorktree;
     private openInEditor;
     private openEditorTool;

package/dist/tui/app.js

@@ -368,8 +368,54 @@ export class WorktreeManagerTUI {
         if (this.isModalOpen)
             return;
         this.isModalOpen = true;
+        // First, show mode selector
+        const modeList = blessed.list({
+            parent: this.screen,
+            left: 'center',
+            top: 'center',
+            width: 50,
+            height: 8,
+            border: { type: 'line' },
+            style: {
+                border: { fg: 'green' },
+                selected: { bg: 'blue', fg: 'white' },
+                bg: 'default'
+            },
+            label: ' Create Worktree ',
+            keys: true,
+            vi: true,
+            items: [
+                '  Create new branch',
+                '  Use existing branch'
+            ]
+        });
+        modeList.focus();
+        this.setStatus(' Select worktree creation mode', 'blue');
+        this.screen.render();
+        const cleanupModeSelector = () => {
+            modeList.destroy();
+            this.screen.render();
+        };
+        modeList.key(['escape'], () => {
+            cleanupModeSelector();
+            this.isModalOpen = false;
+            this.worktreeList.focus();
+            this.setStatus(' Cancelled', 'blue');
+        });
+        modeList.key(['enter'], async () => {
+            const selectedIdx = modeList.selected;
+            cleanupModeSelector();
+            if (selectedIdx === 0) {
+                await this.promptCreateNewBranch();
+            }
+            else {
+                await this.promptUseExistingBranch();
+            }
+        });
+    }
+    async promptCreateNewBranch() {
         this.setStatus(' Loading branches...', 'blue');
-        // Fetch available branches
+        // Fetch available branches for base branch selection
         const branches = await this.git.getBranches();
         if (branches.length === 0) {
             this.setStatus(' Warning: Could not load branches. Using default "main"', 'yellow');
@@ -386,13 +432,13 @@ export class WorktreeManagerTUI {
                 border: { fg: 'green' },
                 bg: 'default'
             },
-            label: ' Create New Worktree '
+            label: ' Create New Branch '
         });
         blessed.text({
             parent: form,
             top: 1,
             left: 2,
-            content: 'Branch name:',
+            content: 'New branch name:',
             style: { fg: 'default' }
         });
         const branchInput = blessed.textbox({
@@ -444,7 +490,7 @@ export class WorktreeManagerTUI {
             style: { fg: 'gray' }
         });
         branchInput.focus();
-        this.setStatus(' Creating new worktree...', 'blue');
+        this.setStatus(' Enter new branch name', 'blue');
         const submitForm = async () => {
             this.isModalOpen = false;
             const branch = branchInput.getValue().replace(/\t/g, '').trim();
@@ -456,7 +502,7 @@ export class WorktreeManagerTUI {
             if (branch) {
                 this.setStatus(` Creating worktree: ${branch} from ${baseBranch}...`, 'blue');
                 try {
-                    await this.git.create({ branch, baseBranch });
+                    await this.git.create({ branch, baseBranch, useExisting: false });
                     await this.refresh();
                     this.setStatus(` Created worktree: ${branch}`, 'green');
                 }
@@ -493,6 +539,119 @@ export class WorktreeManagerTUI {
         });
         this.screen.render();
     }
+    async promptUseExistingBranch() {
+        this.setStatus(' Fetching branches...', 'blue');
+        this.screen.render();
+        // Fetch all branches including remotes
+        const allBranches = await this.git.getAllBranches();
+        if (allBranches.length === 0) {
+            this.isModalOpen = false;
+            this.worktreeList.focus();
+            this.setStatus(' No available branches found (all may already have worktrees)', 'yellow');
+            this.screen.render();
+            return;
+        }
+        const form = blessed.box({
+            parent: this.screen,
+            left: 'center',
+            top: 'center',
+            width: 60,
+            height: 20,
+            border: { type: 'line' },
+            style: {
+                border: { fg: 'cyan' },
+                bg: 'default'
+            },
+            label: ' Select Existing Branch '
+        });
+        blessed.text({
+            parent: form,
+            top: 1,
+            left: 2,
+            content: 'Available branches:',
+            style: { fg: 'default' }
+        });
+        // Format branch items for display
+        const branchItems = allBranches.map(b => {
+            const prefix = b.isRemote ? '{yellow-fg}⬇{/} ' : '  ';
+            const label = b.isRemote ? `${b.fullName}` : b.name;
+            return `${prefix}${label}`;
+        });
+        const branchList = blessed.list({
+            parent: form,
+            top: 3,
+            left: 2,
+            width: 54,
+            height: 12,
+            border: { type: 'line' },
+            style: {
+                border: { fg: 'cyan' },
+                selected: { bg: 'blue', fg: 'white' },
+                focus: { border: { fg: 'green' } }
+            },
+            keys: true,
+            vi: true,
+            mouse: true,
+            tags: true,
+            items: branchItems,
+            scrollbar: {
+                ch: '│',
+                style: { fg: 'cyan' }
+            }
+        });
+        blessed.text({
+            parent: form,
+            top: 16,
+            left: 2,
+            content: '↑↓/jk Navigate | Enter Select | Esc Cancel | {yellow-fg}⬇{/} = remote',
+            tags: true,
+            style: { fg: 'gray' }
+        });
+        branchList.focus();
+        this.setStatus(' Select a branch to create worktree from', 'blue');
+        this.screen.render();
+        const cancelForm = () => {
+            this.isModalOpen = false;
+            form.destroy();
+            this.worktreeList.focus();
+            this.setStatus(' Cancelled', 'blue');
+            this.screen.render();
+        };
+        branchList.key(['escape'], cancelForm);
+        branchList.key(['enter'], async () => {
+            const selectedIdx = branchList.selected;
+            const selectedBranch = allBranches[selectedIdx];
+            this.isModalOpen = false;
+            form.destroy();
+            this.worktreeList.focus();
+            if (selectedBranch) {
+                const displayName = selectedBranch.isRemote ? selectedBranch.fullName : selectedBranch.name;
+                const creatingMsg = selectedBranch.isRemote
+                    ? ` Creating worktree from ${displayName} (will create local tracking branch)...`
+                    : ` Creating worktree for ${displayName}...`;
+                this.setStatus(creatingMsg, 'blue');
+                this.screen.render();
+                try {
+                    await this.git.create({
+                        branch: selectedBranch.fullName,
+                        useExisting: true
+                    });
+                    await this.refresh();
+                    const successMsg = selectedBranch.isRemote
+                        ? ` Created worktree: ${selectedBranch.name} (tracking ${selectedBranch.fullName})`
+                        : ` Created worktree: ${selectedBranch.name}`;
+                    this.setStatus(successMsg, 'green');
+                }
+                catch (error) {
+                    const message = error instanceof GitCommandError
+                        ? error.getUserMessage()
+                        : (error instanceof Error ? error.message : String(error));
+                    this.setStatus(` Error: ${message}`, 'red');
+                }
+            }
+            this.screen.render();
+        });
+    }
     async promptDeleteWorktree() {
         if (this.isModalOpen)
             return;

package/dist/types.d.ts

@@ -34,4 +34,19 @@ export interface CreateWorktreeOptions {
     baseBranch?: string;
     /** Custom path for the worktree (default: auto-generated) */
     path?: string;
+    /** Whether to use an existing branch instead of creating a new one */
+    useExisting?: boolean;
+}
+/**
+ * Represents branch information
+ */
+export interface BranchInfo {
+    /** Branch name (without remote prefix for remote branches) */
+    name: string;
+    /** Full ref name (e.g., 'origin/main' for remote branches) */
+    fullName: string;
+    /** Whether this is a remote branch */
+    isRemote: boolean;
+    /** Remote name if this is a remote branch */
+    remote?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonfutch/worktree-manager",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Terminal app for managing git worktrees with AI assistance",
   "type": "module",
   "main": "dist/index.js",