feat: add --folder flag for custom worktree folder names

[damianlewis]

Problem

Long branch names like feature/implement-user-authentication-with-oauth2-integration create worktree folder names that are too long. When these folder names are used as prefixes for downstream tools (e.g., MySQL database names with a 64-character identifier limit), they exceed the allowed length.

Proposed Solution

Add a --folder <name> option to git gtr new that allows specifying a custom folder name independent of the branch name.

Usage

# Create worktree with short folder name
git gtr new feature/implement-user-authentication-with-oauth2-integration --folder auth

# Reference by folder name or branch name
git gtr editor auth
git gtr go feature/implement-user-authentication-with-oauth2-integration

Behavior

• --folder specifies a complete folder name (replaces default)
• --folder and --name are mutually exclusive
• --force accepts either --name or --folder
• Folder value is sanitized (slashes to hyphens)

Alternatives Considered

• Truncation with hash suffix: Rejected - deviates from core functionality
• Simple truncation: Rejected - risk of collisions

Implementation

I have a working implementation ready to submit as a PR.

[traycerai]

Plan

Observations

The codebase implements a git worktree management tool with a clean architecture. The create_worktree function in file:lib/core.sh currently accepts a custom_name parameter (8th argument) that acts as a suffix to the sanitized branch name. The --name flag is required when using --force to distinguish multiple worktrees on the same branch. The current implementation sanitizes branch names by converting slashes and special characters to hyphens. Worktree resolution in resolve_target() tries direct path matching first, then falls back to searching for matching branches.

Approach

The implementation will add a new --folder flag that specifies a complete folder name (not a suffix), making it mutually exclusive with --name. This addresses the issue of long branch names exceeding downstream tool limits (e.g., MySQL's 64-character identifier limit). The folder name will be sanitized using the existing sanitize_branch_name() function. The --force flag validation will be updated to accept either --name or --folder. This approach maintains backward compatibility while providing the flexibility needed for custom folder naming.

Implementation Steps

1. Update Core Worktree Creation Logic

File: file:lib/core.sh

Modify the create_worktree function (lines 280-408):

• Change the 8th parameter from custom_name to accept both suffix and complete folder name
• Add a 9th parameter use_folder_name (boolean: 0 for suffix mode, 1 for complete folder name mode)
• Update folder name construction logic (lines 292-296):
  • If use_folder_name=1: use sanitized custom name directly as folder name
  • If use_folder_name=0: append custom name as suffix (current behavior)
• Ensure the sanitization logic applies to both modes

2. Update Command Parsing in Main Script

File: file:bin/gtr

Modify the cmd_create function (lines 123-346):

• Add a new variable folder_name="" after line 133
• Add flag parsing for --folder (similar to --name at lines 168-171):

  --folder)
    folder_name="$2"
    shift 2
    ;;
  

• Update validation logic (lines 195-203):
  • Check that --name and --folder are mutually exclusive
  • Update --force validation to require either --name or --folder
  • Add appropriate error messages for invalid combinations
• Update folder name construction for display (lines 248-253):
  • If folder_name is set: use sanitized folder name directly
  • If custom_name is set: use current suffix behavior
  • Otherwise: use sanitized branch name
• Update the create_worktree call (line 260):
  • Pass appropriate parameters based on whether --folder or --name was used
  • Set the 9th parameter accordingly (1 for --folder, 0 for --name)

3. Update Shell Completions

File: file:completions/gtr.bash

Update line 62 to include --folder:

• Add --folder to the completion list for the new command

File: file:completions/git-gtr.fish

Add completion for --folder flag after line 57:

• Add: complete -c git -n '__fish_git_gtr_using_command new' -l folder -d 'Custom folder name (complete replacement)' -r

File: file:completions/_git-gtr

Update line 52 to include --folder:

• Add: '--folder[Custom folder name (complete replacement)]:name:'

4. Update Documentation

File: file:README.md

Update the git gtr new section (lines 153-178):

• Add example showing --folder usage:

  git gtr new feature/implement-user-authentication-with-oauth2-integration --folder auth

• Update the options list to include:
  • --folder <name>: Custom folder name (complete replacement, mutually exclusive with --name)
• Update the --force description to mention it accepts either --name or --folder
• Update the --name description to clarify it's mutually exclusive with --folder

File: file:docs/advanced-usage.md

Update the "Multiple Worktrees Same Branch" section (lines 133-171):

• Add examples showing --folder usage with --force:

  git gtr new feature/long-branch-name --force --folder backend
  git gtr new feature/long-branch-name --force --folder frontend

• Add a subsection explaining when to use --folder vs --name:
  • Use --folder when you need a completely custom name (e.g., to avoid length limits)
  • Use --name when you want to keep the branch name visible in the folder name

File: file:bin/gtr

Update the help text in cmd_help function (lines 1437-1448):

• Update line 1445 to: --folder <name>: custom folder name (complete replacement, mutually exclusive with --name)
• Update line 1444 to mention --force accepts either --name or --folder

5. Update Worktree Resolution Logic

File: file:lib/core.sh

Review the resolve_target function (lines 223-272):

• Verify that the existing logic handles custom folder names correctly
• The current implementation tries direct path match first (line 250-256), which should work for --folder names
• No changes needed if the sanitization is consistent

6. Validation and Edge Cases

Ensure proper handling of:

• Mutual exclusivity: Error if both --name and --folder are provided
• Force validation: Error if --force is used without either --name or --folder
• Sanitization: Apply sanitize_branch_name() to folder names to ensure consistency
• Empty values: Validate that neither --name nor --folder accept empty strings
• Path traversal: Ensure sanitized folder names don't contain .. or absolute paths

Implementation Flow

sequenceDiagram
    participant User
    participant cmd_create
    participant create_worktree
    participant sanitize_branch_name
    participant git

    User->>cmd_create: git gtr new branch --folder custom
    cmd_create->>cmd_create: Parse --folder flag
    cmd_create->>cmd_create: Validate mutual exclusivity
    cmd_create->>sanitize_branch_name: Sanitize folder name
    sanitize_branch_name-->>cmd_create: Sanitized name
    cmd_create->>create_worktree: Call with use_folder_name=1
    create_worktree->>create_worktree: Use folder name directly
    create_worktree->>git: git worktree add
    git-->>create_worktree: Success
    create_worktree-->>cmd_create: Worktree path
    cmd_create-->>User: Worktree created

Loading

Testing Considerations

After implementation, verify:

1. Basic functionality: git gtr new long-branch-name --folder short creates folder named short
2. Sanitization: git gtr new branch --folder my/custom creates folder named my-custom
3. Mutual exclusivity: git gtr new branch --name suffix --folder custom produces error
4. Force validation: git gtr new branch --force produces error (requires --name or --folder)
5. Force with folder: git gtr new branch --force --folder custom1 and git gtr new branch --force --folder custom2 both work
6. Worktree resolution: git gtr editor custom and git gtr go branch both work correctly
7. Backward compatibility: Existing --name functionality remains unchanged

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase implements a git worktree management tool with a clean architecture. The `create_worktree` function in `file:lib/core.sh` currently accepts a `custom_name` parameter (8th argument) that acts as a **suffix** to the sanitized branch name. The `--name` flag is required when using `--force` to distinguish multiple worktrees on the same branch. The current implementation sanitizes branch names by converting slashes and special characters to hyphens. Worktree resolution in `resolve_target()` tries direct path matching first, then falls back to searching for matching branches.

## Approach

The implementation will add a new `--folder` flag that specifies a **complete** folder name (not a suffix), making it mutually exclusive with `--name`. This addresses the issue of long branch names exceeding downstream tool limits (e.g., MySQL's 64-character identifier limit). The folder name will be sanitized using the existing `sanitize_branch_name()` function. The `--force` flag validation will be updated to accept either `--name` or `--folder`. This approach maintains backward compatibility while providing the flexibility needed for custom folder naming.

## Implementation Steps

### 1. Update Core Worktree Creation Logic

**File: `file:lib/core.sh`**

Modify the `create_worktree` function (lines 280-408):

- Change the 8th parameter from `custom_name` to accept both suffix and complete folder name
- Add a 9th parameter `use_folder_name` (boolean: 0 for suffix mode, 1 for complete folder name mode)
- Update folder name construction logic (lines 292-296):
  - If `use_folder_name=1`: use sanitized custom name directly as folder name
  - If `use_folder_name=0`: append custom name as suffix (current behavior)
- Ensure the sanitization logic applies to both modes

### 2. Update Command Parsing in Main Script

**File: `file:bin/gtr`**

Modify the `cmd_create` function (lines 123-346):

- Add a new variable `folder_name=""` after line 133
- Add flag parsing for `--folder` (similar to `--name` at lines 168-171):
  ```
  --folder)
    folder_name="$2"
    shift 2
    ;;
  ```
- Update validation logic (lines 195-203):
  - Check that `--name` and `--folder` are mutually exclusive
  - Update `--force` validation to require either `--name` or `--folder`
  - Add appropriate error messages for invalid combinations
- Update folder name construction for display (lines 248-253):
  - If `folder_name` is set: use sanitized folder name directly
  - If `custom_name` is set: use current suffix behavior
  - Otherwise: use sanitized branch name
- Update the `create_worktree` call (line 260):
  - Pass appropriate parameters based on whether `--folder` or `--name` was used
  - Set the 9th parameter accordingly (1 for `--folder`, 0 for `--name`)

### 3. Update Shell Completions

**File: `file:completions/gtr.bash`**

Update line 62 to include `--folder`:
- Add `--folder` to the completion list for the `new` command

**File: `file:completions/git-gtr.fish`**

Add completion for `--folder` flag after line 57:
- Add: `complete -c git -n '__fish_git_gtr_using_command new' -l folder -d 'Custom folder name (complete replacement)' -r`

**File: `file:completions/_git-gtr`**

Update line 52 to include `--folder`:
- Add: `'--folder[Custom folder name (complete replacement)]:name:'`

### 4. Update Documentation

**File: `file:README.md`**

Update the `git gtr new` section (lines 153-178):

- Add example showing `--folder` usage:
  ```bash
  git gtr new feature/implement-user-authentication-with-oauth2-integration --folder auth
  ```
- Update the options list to include:
  - `--folder <name>`: Custom folder name (complete replacement, mutually exclusive with --name)
- Update the `--force` description to mention it accepts either `--name` or `--folder`
- Update the `--name` description to clarify it's mutually exclusive with `--folder`

**File: `file:docs/advanced-usage.md`**

Update the "Multiple Worktrees Same Branch" section (lines 133-171):

- Add examples showing `--folder` usage with `--force`:
  ```bash
  git gtr new feature/long-branch-name --force --folder backend
  git gtr new feature/long-branch-name --force --folder frontend
  ```
- Add a subsection explaining when to use `--folder` vs `--name`:
  - Use `--folder` when you need a completely custom name (e.g., to avoid length limits)
  - Use `--name` when you want to keep the branch name visible in the folder name

**File: `file:bin/gtr`**

Update the help text in `cmd_help` function (lines 1437-1448):

- Update line 1445 to: `--folder <name>: custom folder name (complete replacement, mutually exclusive with --name)`
- Update line 1444 to mention `--force` accepts either `--name` or `--folder`

### 5. Update Worktree Resolution Logic

**File: `file:lib/core.sh`**

Review the `resolve_target` function (lines 223-272):

- Verify that the existing logic handles custom folder names correctly
- The current implementation tries direct path match first (line 250-256), which should work for `--folder` names
- No changes needed if the sanitization is consistent

### 6. Validation and Edge Cases

Ensure proper handling of:

- **Mutual exclusivity**: Error if both `--name` and `--folder` are provided
- **Force validation**: Error if `--force` is used without either `--name` or `--folder`
- **Sanitization**: Apply `sanitize_branch_name()` to folder names to ensure consistency
- **Empty values**: Validate that neither `--name` nor `--folder` accept empty strings
- **Path traversal**: Ensure sanitized folder names don't contain `..` or absolute paths

## Implementation Flow

```mermaid
sequenceDiagram
    participant User
    participant cmd_create
    participant create_worktree
    participant sanitize_branch_name
    participant git

    User->>cmd_create: git gtr new branch --folder custom
    cmd_create->>cmd_create: Parse --folder flag
    cmd_create->>cmd_create: Validate mutual exclusivity
    cmd_create->>sanitize_branch_name: Sanitize folder name
    sanitize_branch_name-->>cmd_create: Sanitized name
    cmd_create->>create_worktree: Call with use_folder_name=1
    create_worktree->>create_worktree: Use folder name directly
    create_worktree->>git: git worktree add
    git-->>create_worktree: Success
    create_worktree-->>cmd_create: Worktree path
    cmd_create-->>User: Worktree created
```

## Testing Considerations

After implementation, verify:

1. **Basic functionality**: `git gtr new long-branch-name --folder short` creates folder named `short`
2. **Sanitization**: `git gtr new branch --folder my/custom` creates folder named `my-custom`
3. **Mutual exclusivity**: `git gtr new branch --name suffix --folder custom` produces error
4. **Force validation**: `git gtr new branch --force` produces error (requires --name or --folder)
5. **Force with folder**: `git gtr new branch --force --folder custom1` and `git gtr new branch --force --folder custom2` both work
6. **Worktree resolution**: `git gtr editor custom` and `git gtr go branch` both work correctly
7. **Backward compatibility**: Existing `--name` functionality remains unchanged

---

Execution Information

Branch: main
Commit: 7a315d7

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.