feat: add configurable branch separator for branchSafe variable (#48)

* feat: replace {.branchSafe} with configurable separator for template values

Remove the {.branchSafe} template variable and introduce a unified
'separator' config option that controls how '/' and '\' in value
variables ({.branch}, {.repo.Owner}, {.env.*}) are replaced.

Path variables ({.repo.Main}, {.worktreeRoot}) are never transformed.
Default separator is '/' (backward compatible - slashes create subdirs).
Set to '-' or '_' for flat paths (e.g. feat/foo -> feat-foo).

Configuration: TOML key 'separator', env var WORKTREE_SEPARATOR.
Uses os.LookupEnv so empty string is a valid value.

* fix: skip empty separator E2E test on Windows

PowerShell treats empty environment variables as unset, so
WORKTREE_SEPARATOR="" is not observable via os.LookupEnv on Windows.

Author: timvw

README.md

@@ -271,6 +271,10 @@ root = "~/projects/worktrees"
 # Worktree placement strategy
 strategy = "sibling-repo"
 
+# Separator replaces "/" and "\" in value variables ({.branch}, {.repo.Owner}, {.env.*})
+# Default "/" preserves slashes (nested dirs). Set to "-" or "_" for flat paths.
+# separator = "/"
+
 # Custom pattern (used when strategy = "custom", or to override any strategy's default)
 # pattern = "{.worktreeRoot}/{.repo.Name}/{.branch}"
 ```
@@ -280,7 +284,7 @@ strategy = "sibling-repo"
 Configuration values are resolved in this order (highest priority first):
 
 1. **CLI flags** (`--config`)
-2. **Environment variables** (`WORKTREE_ROOT`, `WORKTREE_STRATEGY`, `WORKTREE_PATTERN`)
+2. **Environment variables** (`WORKTREE_ROOT`, `WORKTREE_STRATEGY`, `WORKTREE_PATTERN`, `WORKTREE_SEPARATOR`)
 3. **Config file** (`~/.config/wt/config.toml`)
 4. **Built-in defaults**
 
@@ -295,35 +299,56 @@ Configure the location with environment variables or the config file:
 - `WORKTREE_ROOT` / `root` (default: `~/dev/worktrees`)
 - `WORKTREE_STRATEGY` / `strategy` (`global`, `sibling-repo`, `parent-branches`, `parent-worktrees`, `parent-dotdir`, `inside-dotdir`, `custom`)
 - `WORKTREE_PATTERN` / `pattern` (optional; overrides the default structure within the chosen strategy)
+- `WORKTREE_SEPARATOR` / `separator` (default: `/`; controls how `/` and `\` in value variables are replaced)
 
 Available pattern variables:
 
 - `{.repo.Name}` repo name
-- `{.repo.Main}` main branch worktree path
+- `{.repo.Main}` main branch worktree path (path variable, not transformed by separator)
 - `{.repo.Owner}` repo owner/group (from origin URL)
 - `{.repo.Host}` git host (from origin URL)
 - `{.branch}` git branch name
-- `{.branchSafe}` git branch name (sanitized for filesystem paths)
-- `{.worktreeRoot}` value of `WORKTREE_ROOT`
+- `{.worktreeRoot}` value of `WORKTREE_ROOT` (path variable, not transformed by separator)
 - `{.env.VARNAME}` value of environment variable `VARNAME` (e.g. `{.env.USER}`, `{.env.HOME}`)
 
 Default patterns per strategy:
 
 | Strategy | Description | Default pattern |
 | --- | --- | --- |
 | `global` | worktrees under a global directory | `{.worktreeRoot}/{.repo.Name}/{.branch}` |
-| `sibling-repo` | worktrees next to the main repo directory | `{.repo.Main}/../{.repo.Name}-{.branchSafe}` |
+| `sibling-repo` | worktrees next to the main repo directory | `{.repo.Main}/../{.repo.Name}-{.branch}` |
 | `parent-branches` | branches as siblings of main | `{.repo.Main}/../{.branch}` |
 | `parent-worktrees` | branches under `<repo>.worktrees/` | `{.repo.Main}/../{.repo.Name}.worktrees/{.branch}` |
 | `parent-dotdir` | branches under `.worktrees/` next to main | `{.repo.Main}/../.worktrees/{.branch}` |
 | `inside-dotdir` | branches under `.worktrees/` inside main | `{.repo.Main}/.worktrees/{.branch}` |
 | `custom` | user-defined pattern | `WORKTREE_PATTERN` |
 
+### Separator
+
+The `separator` setting controls how `/` and `\` characters in **value variables** (`{.branch}`, `{.repo.Owner}`, `{.env.*}`) are replaced. **Path variables** (`{.repo.Main}`, `{.worktreeRoot}`) are never transformed.
+
+| Separator | Branch `feat/foo` becomes | Use case |
+| --- | --- | --- |
+| `/` (default) | `feat/foo` (nested dirs) | Standard layout |
+| `-` | `feat-foo` (flat) | Sibling-repo, flat directories |
+| `_` | `feat_foo` (flat) | Alternative flat layout |
+| `""` | `featfoo` | Compact (rarely used) |
+
+```toml
+# ~/.config/wt/config.toml
+separator = "-"   # feat/foo -> feat-foo
+```
+
+```bash
+export WORKTREE_SEPARATOR="-"
+```
+
 Customize the location via environment variables:
 
 ```bash
 export WORKTREE_ROOT="$HOME/projects/worktrees"
 export WORKTREE_STRATEGY="sibling-repo"
+export WORKTREE_SEPARATOR="-"
 export WORKTREE_PATTERN="{.repo.Main}/../{.repo.Name}/{.branch}"
 ```
 
@@ -332,6 +357,7 @@ Or via config file:
 ```toml
 root = "~/projects/worktrees"
 strategy = "sibling-repo"
+separator = "-"
 pattern = "{.repo.Main}/../{.repo.Name}/{.branch}"
 ```
 

config.go

@@ -12,16 +12,18 @@ import (
 
 // Config represents the wt configuration file structure.
 type Config struct {
-	Root     string `toml:"root"`
-	Strategy string `toml:"strategy"`
-	Pattern  string `toml:"pattern"`
+	Root      string `toml:"root"`
+	Strategy  string `toml:"strategy"`
+	Pattern   string `toml:"pattern"`
+	Separator string `toml:"separator"`
 }
 
 // configSource tracks where each config value came from.
 type configSource struct {
-	Root     string
-	Strategy string
-	Pattern  string
+	Root      string
+	Strategy  string
+	Pattern   string
+	Separator string
 }
 
 // configFilePath is the resolved path to the config file (set during loading).
@@ -50,10 +52,16 @@ const defaultConfigTemplate = `# wt configuration file
 
 # Custom pattern (used when strategy = "custom", or to override any strategy's default)
 # Available variables: {.worktreeRoot}, {.repo.Name}, {.repo.Main},
-#                      {.repo.Owner}, {.repo.Host}, {.branch}, {.branchSafe},
+#                      {.repo.Owner}, {.repo.Host}, {.branch},
 #                      {.env.VARNAME} (access environment variables, e.g. {.env.USER})
 # pattern = "{.worktreeRoot}/{.repo.Name}/{.branch}"
 
+# Separator replaces "/" and "\" in template value variables ({.branch}, {.repo.Owner}, {.env.*})
+# Default is "/" (no transformation — slashes create subdirectories).
+# Set to "-" or "_" for flat paths (e.g. feat/foo -> feat-foo).
+# Does NOT affect path variables ({.repo.Main}, {.worktreeRoot}).
+# separator = "/"
+
 # Example: group worktrees by a FEATURE environment variable
 # strategy = "custom"
 # pattern = "{.worktreeRoot}/{.env.FEATURE}/{.repo.Name}"
@@ -95,11 +103,13 @@ func loadWorktreeConfig() {
 	worktreeRoot = defaultRoot
 	worktreeStrategy = "global"
 	worktreePattern = ""
+	worktreeSeparator = "/"
 
 	configSources = configSource{
-		Root:     "default",
-		Strategy: "default",
-		Pattern:  "default",
+		Root:      "default",
+		Strategy:  "default",
+		Pattern:   "default",
+		Separator: "default",
 	}
 
 	// 2. Load config file
@@ -122,6 +132,10 @@ func loadWorktreeConfig() {
 				worktreePattern = strings.TrimSpace(cfg.Pattern)
 				configSources.Pattern = "config file"
 			}
+			if cfg.Separator != "" {
+				worktreeSeparator = cfg.Separator
+				configSources.Separator = "config file"
+			}
 		}
 	}
 
@@ -138,6 +152,10 @@ func loadWorktreeConfig() {
 		worktreePattern = strings.TrimSpace(v)
 		configSources.Pattern = "env: WORKTREE_PATTERN"
 	}
+	if v, ok := os.LookupEnv("WORKTREE_SEPARATOR"); ok {
+		worktreeSeparator = v
+		configSources.Separator = "env: WORKTREE_SEPARATOR"
+	}
 }
 
 // expandHome replaces a leading ~ with the user's home directory.

e2e/scenarios/info.yaml

@@ -10,7 +10,7 @@ scenarios:
       - run: $WT_BIN info
         expect:
           exit_code: 0
-          output_contains: "Strategy: global"
+          output_contains: "Strategy:  global"
       - run: $WT_BIN info
         expect:
           output_contains: "Pattern variables:"
@@ -24,4 +24,4 @@ scenarios:
           WORKTREE_STRATEGY: sibling-repo
         expect:
           exit_code: 0
-          output_contains: "Strategy: sibling-repo"
+          output_contains: "Strategy:  sibling-repo"

e2e/scenarios/separator.yaml

@@ -0,0 +1,114 @@
+# E2E tests for the separator configuration
+name: separator
+description: Test WORKTREE_SEPARATOR controls how slashes in value variables are replaced
+
+scenarios:
+  - name: separator_default_preserves_slashes
+    description: Default separator "/" preserves slashes as subdirectories
+    steps:
+      - run: wt create feature/deep/branch
+        env:
+          WORKTREE_STRATEGY: global
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/feature/deep/branch
+
+  - name: separator_dash
+    description: Separator "-" replaces slashes with dashes
+    steps:
+      - run: wt create feature/dash-test
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "-"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/feature-dash-test
+
+  - name: separator_underscore
+    description: Separator "_" replaces slashes with underscores
+    steps:
+      - run: wt create feature/underscore-test
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "_"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/feature_underscore-test
+
+  - name: separator_double_dash
+    description: Separator "--" replaces slashes with double dashes
+    steps:
+      - run: wt create feature/double
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "--"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/feature--double
+
+  - name: separator_empty_removes_slashes
+    description: Empty separator removes slashes entirely
+    skip_os: [windows]  # PowerShell treats empty env vars as unset
+    steps:
+      - run: wt create feature/empty
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: ""
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/featureempty
+
+  - name: separator_with_sibling_repo
+    description: Separator works with sibling-repo strategy
+    steps:
+      - run: wt create feature/sibling-sep
+        env:
+          WORKTREE_STRATEGY: sibling-repo
+          WORKTREE_SEPARATOR: "-"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /test-repo-feature-sibling-sep
+
+  - name: separator_multiple_slashes
+    description: Separator replaces multiple slashes in branch name
+    steps:
+      - run: wt create a/b/c/d
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "_"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/a_b_c_d
+
+  - name: separator_no_effect_without_slashes
+    description: Separator has no effect on branches without slashes
+    steps:
+      - run: wt create simple-branch
+        env:
+          WORKTREE_STRATEGY: custom
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "-"
+        expect:
+          exit_code: 0
+      - run: pwd
+        expect:
+          cwd_ends_with: /worktrees/test-repo/simple-branch

e2e/scenarios/worktree-strategy.yaml

@@ -21,6 +21,7 @@ scenarios:
       - run: wt create feature/sibling
         env:
           WORKTREE_STRATEGY: sibling-repo
+          WORKTREE_SEPARATOR: "-"
         expect:
           exit_code: 0
       - run: pwd
@@ -100,12 +101,13 @@ scenarios:
           exit_code: 1
 
   - name: strategy_branch_sanitized
-    description: Branch names are sanitized when using branchSafe
+    description: Separator replaces slashes in branch names
     steps:
       - run: wt create feature/sanitized
         env:
           WORKTREE_STRATEGY: custom
-          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branchSafe}"
+          WORKTREE_PATTERN: "{.worktreeRoot}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "-"
         expect:
           exit_code: 0
       - run: pwd
@@ -158,7 +160,8 @@ scenarios:
         env:
           WORKTREE_ROOT: worktrees
           WORKTREE_STRATEGY: custom
-          WORKTREE_PATTERN: "{.repo.Main}/../{.worktreeRoot}/custom/{.repo.Host}/{.repo.Owner}/{.repo.Name}/{.branchSafe}"
+          WORKTREE_PATTERN: "{.repo.Main}/../{.worktreeRoot}/custom/{.repo.Host}/{.repo.Owner}/{.repo.Name}/{.branch}"
+          WORKTREE_SEPARATOR: "-"
         expect:
           exit_code: 0
       - run: pwd
@@ -192,6 +195,7 @@ scenarios:
       - run: wt checkout checkout-sibling-branch
         env:
           WORKTREE_STRATEGY: sibling-repo
+          WORKTREE_SEPARATOR: "-"
         expect:
           exit_code: 0
       - run: pwd
@@ -206,6 +210,7 @@ scenarios:
       - run: wt checkout remove-sibling-branch
         env:
           WORKTREE_STRATEGY: sibling-repo
+          WORKTREE_SEPARATOR: "-"
         expect:
           exit_code: 0
       - cd: $REPO_DIR