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
• bin/gtr: Add collision guard for next steps when --folder value matches current branch
• lib/core.sh: Add folder_override parameter to create_worktree()
• lib/core.sh: Add validation to reject empty, ., and .. folder names (path traversal protection)
• 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
• Collision guard: --folder main while on main branch shows branch name in next steps
• Path traversal validation: --folder "." rejected
• Path traversal validation: --folder ".." rejected
• Path traversal validation: --folder "///" (empty after sanitization) rejected
• Valid edge cases: --folder "..valid", --folder "valid.." work correctly
• Normal worktree creation (without --folder) still works
• --name flag still works

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.
  • 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.

• Bug Fixes

  • Improved error messaging and collision-avoidance in post-create guidance.

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

[coderabbitai]

🚥 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 title accurately summarizes the main feature being added—a --folder flag for custom worktree folder names, which is the primary change across the changeset.
Linked Issues check	✅ Passed	The pull request implements all core coding requirements from issue #81: --folder flag with mutual exclusivity vs --name, --force compatibility, folder sanitization, and completion updates.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the --folder feature as specified in issue #81; documentation, completions, and core logic changes 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 docstrings

🧪 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

[damianlewis]

@helizaga I've added two fixes to address CR comments.