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

[damianlewis]

Summary

• Add --folder option to git gtr new for specifying custom folder names
• Allows decoupling folder name from branch name (useful for long branch names)
• Updates validation, help text, and shell completions

Closes #81

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

Changes

• bin/gtr: Add --folder flag parsing, validation, and help text
• lib/core.sh: Add folder_override parameter to create_worktree()
• completions/: Add --folder to bash, zsh, and fish completions
• README.md: Document --folder option with examples

Testing performed

• Basic --folder usage creates correct folder
• Reference worktree by folder name works
• Reference worktree by branch name works
• --folder and --name mutual exclusivity error
• --force requires --name or --folder error
• --force with --folder works
• Folder value sanitization (slashes to hyphens)
• Help text shows --folder option
• Next steps shows folder name with --folder, branch name otherwise

Summary by CodeRabbit

• New Features

  • Added a --folder option to specify a custom worktree folder name (overrides default naming).
  • --folder and --name are mutually exclusive; --force now accepts either --name or --folder to distinguish worktrees.
  • Next-step messages and navigation use the effective folder identifier when a folder override is supplied.

• Documentation

  • Updated README, help text, and shell completions to document --folder and its interaction with --force.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@damianlewis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 31 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 96b691f and b1b8709.

📒 Files selected for processing (1)

• README.md

Walkthrough

Adds a new --folder flag to git gtr new to specify a custom worktree folder name (sanitized). The flag is mutually exclusive with --name, is accepted by --force, updates folder-name construction in create_worktree, and updates documentation and shell completions.

Changes

Cohort / File(s)	Summary
CLI entrypoint bin/gtr	Adds --folder / folder_override handling; enforces mutual exclusion with --name; accepts --folder with --force; passes folder override into create_worktree; updates help/examples and next-step messages
Core library lib/core.sh	create_worktree signature gains folder_override (9th param); folder-name construction uses sanitized folder_override when present, otherwise existing custom/branch logic
Documentation README.md	Adds example and documents --folder; updates --force description to require either --name or --folder
Shell completions completions/_git-gtr, completions/git-gtr.fish, completions/gtr.bash	Adds --folder flag/argument to zsh, fish, and bash completion scripts for the new subcommand

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as bin/gtr
  participant Core as lib/core.sh
  participant GitFS as Git/Filesystem

  User->>CLI: git gtr new <branch> --folder <name> [--force]
  CLI->>CLI: parse flags, validate (--folder xor --name), allow --force with folder
  CLI->>Core: call create_worktree(base_dir, repo, branch, ... , custom_name, folder_override)
  Core->>Core: sanitize folder_override (if present) -> determine folder_name
  Core->>GitFS: create worktree at <base_dir>/<folder_name>
  GitFS-->>Core: success / error
  Core-->>CLI: result + effective identifier (folder_name or branch)
  CLI-->>User: display next steps referencing effective identifier

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I found a flag to shape my den,
Short names now skip the long-branch pen.
Hop in a folder, neat and spry,
No more slashes stretching high.
Cheers — a tidy worktree, from me to you. 🌿✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately and concisely summarizes the main change: adding a --folder flag for custom worktree folder names, which is the primary objective of the changeset.
Linked Issues check	✅ Passed	All coding requirements from issue #81 are met: --folder flag is implemented with mutual exclusivity to --name [#81], --force accepts either flag [#81], folder sanitization is applied [#81], and completions are updated across all shells [#81].
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #81 objectives: flag implementation, mutual exclusivity enforcement, folder sanitization, help text updates, completion additions, and README documentation are all in scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@bin/gtr`:
- Around line 353-367: When computing next_steps_id for displayed commands
(variables: next_steps_id, folder_override, folder_name, branch_name), add a
collision guard so that if folder_override is set but the resolved target (use
resolve_target) would point to the main repo or otherwise equals the current
branch_name, fall back to using branch_name (or include both identifiers)
instead of folder_name; update the logic that builds next_steps_id and the
subsequent echo lines for the git gtr editor/ai/go suggestions to use the safe
identifier so the suggested commands don't accidentally reference the main repo.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/core.sh (1)

293-300: Validate --folder against empty / “.” / “..” to prevent base-dir escape.
Sanitization doesn’t block “.” or “..”; those values would resolve to the base dir or its parent. Add a guard after computing sanitized_name.

🛠️ Proposed fix

   if [ -n "$folder_override" ]; then
     sanitized_name=$(sanitize_branch_name "$folder_override")
   elif [ -n "$custom_name" ]; then
     sanitized_name="$(sanitize_branch_name "$branch_name")-${custom_name}"
   else
     sanitized_name=$(sanitize_branch_name "$branch_name")
   fi
+
+  if [ -z "$sanitized_name" ] || [ "$sanitized_name" = "." ] || [ "$sanitized_name" = ".." ]; then
+    if [ -n "$folder_override" ]; then
+      log_error "Invalid --folder value: $folder_override"
+    else
+      log_error "Invalid worktree folder name derived from branch: $branch_name"
+    fi
+    return 1
+  fi

♻️ Duplicate comments (1)

bin/gtr (1)

353-367: Next-steps identifier can still collide with current branch name.
Same concern as earlier: if --folder matches the repo’s current branch, the suggested commands target the main repo instead of the new worktree.

[helizaga]

looks goodl! nit: folder main while on main branch causes git gtr go main to resolve to the main repo instead of the worktree. might want that collision guard CR suggested