feat: add support for configuring branch name prefix (#75)

* feat: support branch prefix for implicit add names

Co-authored-by: Safia Abdalla <safia@safia.rocks>

* fix: keep implicit worktree directories unprefixed

Co-authored-by: Safia Abdalla <safia@safia.rocks>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: captainsafia

README.md

@@ -87,6 +87,8 @@ Create a new worktree with an auto-generated adjective-noun name:
 ```bash
 grove add
 # Example generated name: quiet-meadow
+# If .groverc sets "branchPrefix": "safia", example: safia/quiet-meadow
+# Directory remains: quiet-meadow
 ```
 
 Track a remote branch:
@@ -99,6 +101,7 @@ Bootstrap a newly created worktree with project-scoped commands:
 
 ```json
 {
+  "branchPrefix": "safia",
   "bootstrap": {
     "commands": [
       { "program": "npm", "args": ["install"] },
@@ -110,6 +113,8 @@ Bootstrap a newly created worktree with project-scoped commands:
 
 Save this as `.groverc` in your Grove project root (the directory that contains your bare clone, for example `repo/.groverc` next to `repo/repo.git`).
 
+When `grove add` is called without an explicit branch name, Grove generates an adjective-noun name and prepends `branchPrefix` to the branch name when configured. The worktree directory keeps the generated base name.
+
 When `grove add` creates a worktree, it runs each bootstrap command in order inside that new worktree directory.
 
 - Commands must be portable across Linux/macOS/Windows.

site/index.html

@@ -799,11 +799,14 @@ <h3>Add a new worktree</h3>
                     <pre><code>grove add feature-branch</code></pre>
                     <p>Or let Grove generate a default adjective-noun name:</p>
                     <pre><code>grove add
-# Example generated name: quiet-meadow</code></pre>
+# Example generated name: quiet-meadow
+# If .groverc sets "branchPrefix": "safia", example: safia/quiet-meadow
+# Directory remains: quiet-meadow</code></pre>
                     <p>With tracking for a remote branch:</p>
                     <pre><code>grove add feature-branch --track origin/feature-branch</code></pre>
                     <p>Optional bootstrap commands from <code>.groverc</code> run in the new worktree:</p>
                     <pre><code>{
+  "branchPrefix": "safia",
   "bootstrap": {
     "commands": [
       { "program": "npm", "args": ["install"] },
@@ -812,6 +815,7 @@ <h3>Add a new worktree</h3>
   }
 }</code></pre>
                     <p>Place <code>.groverc</code> in the Grove project root (next to the bare clone directory).</p>
+                    <p>When <code>grove add</code> is called without an explicit branch name, Grove generates an adjective-noun name and prepends <code>branchPrefix</code> to the branch name when configured. The worktree directory keeps the generated base name.</p>
                     <p>Commands must be portable across Linux/macOS/Windows and use executable + args only (no shell operators like <code>&amp;&amp;</code> or pipes). If one command fails, Grove continues and reports a partial bootstrap state.</p>
                 </div>
 

src/commands/add.rs

@@ -6,8 +6,8 @@ use crate::git::{
     add_worktree, branch_exists, discover_repo, project_root, tracked_branch_name, RepoContext,
 };
 use crate::utils::{
-    default_worktree_name_seed, generate_default_worktree_name, read_repo_config, BootstrapCommand,
-    DEFAULT_WORKTREE_NAME_ATTEMPTS,
+    default_worktree_name_seed, generate_default_worktree_name, read_repo_config,
+    trim_trailing_branch_slashes, BootstrapCommand, RepoConfig, DEFAULT_WORKTREE_NAME_ATTEMPTS,
 };
 
 #[derive(Debug)]
@@ -17,6 +17,12 @@ struct BootstrapSummary {
     failed: Vec<(String, String)>,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct WorktreeSpec {
+    directory_name: String,
+    branch_name: String,
+}
+
 pub fn run(name: Option<&str>, track: Option<&str>) {
     let repo = match discover_repo() {
         Ok(m) => m,
@@ -27,14 +33,21 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
     };
 
     let project_root = project_root(&repo);
-    let worktree_name = match resolve_worktree_name(name, &repo, project_root) {
-        Ok(name) => name,
+    let repo_config = match read_repo_config(project_root) {
+        Ok(config) => config,
+        Err(e) => {
+            eprintln!("{} {}", "Warning:".yellow(), e);
+            RepoConfig::default()
+        }
+    };
+    let worktree = match resolve_worktree_spec(name, &repo, project_root, &repo_config) {
+        Ok(worktree) => worktree,
         Err(e) => {
             eprintln!("{} {}", "Error:".red(), e);
             std::process::exit(1);
         }
     };
-    let worktree_path = match get_worktree_path(&worktree_name, project_root) {
+    let worktree_path = match get_worktree_path(&worktree.directory_name, project_root) {
         Ok(p) => p,
         Err(e) => {
             eprintln!("{} {}", "Error:".red(), e);
@@ -43,7 +56,7 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
     };
 
     let worktree_path_str = worktree_path.to_string_lossy().to_string();
-    let target_branch = match resolve_target_branch(&worktree_name, track) {
+    let target_branch = match resolve_target_branch(&worktree.branch_name, track) {
         Ok(branch) => branch,
         Err(e) => {
             eprintln!("{} {}", "Error:".red(), e);
@@ -58,10 +71,10 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
         match add_worktree(&repo, &worktree_path_str, &target_branch, true, track) {
             Ok(()) => is_new_branch = true,
             Err(new_err) => {
-                let worktree_and_branch = if target_branch == worktree_name {
-                    worktree_name.clone()
+                let worktree_and_branch = if target_branch == worktree.directory_name {
+                    worktree.directory_name.clone()
                 } else {
-                    format!("{} (branch: {})", worktree_name, target_branch)
+                    format!("{} (branch: {})", worktree.directory_name, target_branch)
                 };
                 eprintln!(
                     "{} Failed to create worktree for '{}':\n  As existing branch: {}\n  As new branch: {}",
@@ -75,10 +88,10 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
         }
     }
 
-    let worktree_and_branch = if target_branch == worktree_name {
-        worktree_name.clone()
+    let worktree_and_branch = if target_branch == worktree.directory_name {
+        worktree.directory_name.clone()
     } else {
-        format!("{} (branch: {})", worktree_name, target_branch)
+        format!("{} (branch: {})", worktree.directory_name, target_branch)
     };
     if is_new_branch {
         println!(
@@ -95,14 +108,6 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
     }
     println!("{}", format!("Path: {}", worktree_path_str).dimmed());
 
-    let repo_config = match read_repo_config(project_root) {
-        Ok(config) => config,
-        Err(e) => {
-            eprintln!("{} {}", "Warning:".yellow(), e);
-            return;
-        }
-    };
-
     let commands = match repo_config.bootstrap {
         Some(bootstrap) if !bootstrap.commands.is_empty() => bootstrap.commands,
         _ => return,
@@ -140,22 +145,31 @@ pub fn run(name: Option<&str>, track: Option<&str>) {
     }
 }
 
-fn resolve_worktree_name(
+fn resolve_worktree_spec(
     provided_name: Option<&str>,
     repo: &RepoContext,
     project_root: &Path,
-) -> Result<String, String> {
+    repo_config: &RepoConfig,
+) -> Result<WorktreeSpec, String> {
     if let Some(name) = provided_name {
-        return Ok(name.to_string());
+        return Ok(WorktreeSpec {
+            directory_name: name.to_string(),
+            branch_name: name.to_string(),
+        });
     }
 
-    choose_default_worktree_name(repo, project_root)
+    choose_default_worktree_spec(repo, project_root, repo_config.branch_prefix.as_deref())
 }
 
-fn choose_default_worktree_name(repo: &RepoContext, project_root: &Path) -> Result<String, String> {
+fn choose_default_worktree_spec(
+    repo: &RepoContext,
+    project_root: &Path,
+    branch_prefix: Option<&str>,
+) -> Result<WorktreeSpec, String> {
     let seed = default_worktree_name_seed();
     for attempt in 0..DEFAULT_WORKTREE_NAME_ATTEMPTS {
-        let candidate = generate_default_worktree_name(seed, attempt);
+        let generated_name = generate_default_worktree_name(seed, attempt);
+        let candidate = generated_worktree_spec(branch_prefix, &generated_name);
         if is_name_available(repo, project_root, &candidate) {
             return Ok(candidate);
         }
@@ -167,12 +181,30 @@ fn choose_default_worktree_name(repo: &RepoContext, project_root: &Path) -> Resu
     )
 }
 
-fn is_name_available(repo: &RepoContext, project_root: &Path, candidate: &str) -> bool {
-    if branch_exists(repo, candidate) {
+fn is_name_available(repo: &RepoContext, project_root: &Path, candidate: &WorktreeSpec) -> bool {
+    if branch_exists(repo, &candidate.branch_name) {
         return false;
     }
 
-    !project_root.join(candidate).exists()
+    !project_root.join(&candidate.directory_name).exists()
+}
+
+fn generated_worktree_spec(branch_prefix: Option<&str>, generated_name: &str) -> WorktreeSpec {
+    WorktreeSpec {
+        directory_name: generated_name.to_string(),
+        branch_name: apply_branch_prefix(branch_prefix, generated_name),
+    }
+}
+
+fn apply_branch_prefix(branch_prefix: Option<&str>, generated_name: &str) -> String {
+    let Some(prefix) = branch_prefix
+        .map(trim_trailing_branch_slashes)
+        .filter(|prefix| !prefix.is_empty())
+    else {
+        return generated_name.to_string();
+    };
+
+    format!("{}/{}", prefix, generated_name)
 }
 
 fn resolve_target_branch(name: &str, track: Option<&str>) -> Result<String, String> {
@@ -504,4 +536,36 @@ mod tests {
         let result = resolve_target_branch("foo", Some("refs/heads/feature/new-ui"));
         assert!(result.is_err());
     }
+
+    #[test]
+    fn apply_branch_prefix_adds_separator_when_configured() {
+        let prefixed = apply_branch_prefix(Some("safia"), "quiet-meadow");
+        assert_eq!(prefixed, "safia/quiet-meadow");
+    }
+
+    #[test]
+    fn apply_branch_prefix_trims_whitespace_and_trailing_slashes() {
+        let prefixed = apply_branch_prefix(Some("  teams/safia/  "), "quiet-meadow");
+        assert_eq!(prefixed, "teams/safia/quiet-meadow");
+    }
+
+    #[test]
+    fn apply_branch_prefix_ignores_empty_prefix() {
+        let unprefixed = apply_branch_prefix(Some("  /  "), "quiet-meadow");
+        assert_eq!(unprefixed, "quiet-meadow");
+    }
+
+    #[test]
+    fn generated_worktree_spec_applies_prefix_only_to_branch_name() {
+        let spec = generated_worktree_spec(Some("safia"), "quiet-meadow");
+        assert_eq!(spec.directory_name, "quiet-meadow");
+        assert_eq!(spec.branch_name, "safia/quiet-meadow");
+    }
+
+    #[test]
+    fn generated_worktree_spec_without_prefix_keeps_names_equal() {
+        let spec = generated_worktree_spec(None, "quiet-meadow");
+        assert_eq!(spec.directory_name, "quiet-meadow");
+        assert_eq!(spec.branch_name, "quiet-meadow");
+    }
 }

src/utils.rs

@@ -61,6 +61,8 @@ pub struct RepoBootstrapConfig {
 pub struct RepoConfig {
     #[serde(default)]
     pub bootstrap: Option<RepoBootstrapConfig>,
+    #[serde(rename = "branchPrefix", default)]
+    pub branch_prefix: Option<String>,
 }
 
 /// Read the grove config file.
@@ -698,6 +700,7 @@ mod tests {
         let dir = make_temp_dir("repo-config-missing");
         let config = read_repo_config(&dir).unwrap();
         assert!(config.bootstrap.is_none());
+        assert!(config.branch_prefix.is_none());
         let _ = fs::remove_dir_all(dir);
     }
 
@@ -707,6 +710,7 @@ mod tests {
         fs::write(
             dir.join(".groverc"),
             r#"{
+  "branchPrefix": "safia",
   "bootstrap": {
     "commands": [
       { "program": "npm", "args": ["install"] },
@@ -718,6 +722,7 @@ mod tests {
         .unwrap();
 
         let config = read_repo_config(&dir).unwrap();
+        assert_eq!(config.branch_prefix.as_deref(), Some("safia"));
         let bootstrap = config.bootstrap.unwrap();
         assert_eq!(bootstrap.commands.len(), 2);
         assert_eq!(bootstrap.commands[0].program, "npm");
@@ -727,6 +732,23 @@ mod tests {
         let _ = fs::remove_dir_all(dir);
     }
 
+    #[test]
+    fn read_repo_config_parses_branch_prefix_without_bootstrap() {
+        let dir = make_temp_dir("repo-config-prefix-only");
+        fs::write(
+            dir.join(".groverc"),
+            r#"{
+  "branchPrefix": "teams/safia"
+}"#,
+        )
+        .unwrap();
+
+        let config = read_repo_config(&dir).unwrap();
+        assert_eq!(config.branch_prefix.as_deref(), Some("teams/safia"));
+        assert!(config.bootstrap.is_none());
+        let _ = fs::remove_dir_all(dir);
+    }
+
     #[test]
     fn read_repo_config_rejects_string_commands_schema() {
         let dir = make_temp_dir("repo-config-string-schema");