@getsolaris/copse 1.0.2 → 1.1.0

package/README.ko.md

@@ -10,6 +10,10 @@
 
 Git worktree를 쉽게 관리하세요. 설정 기반 자동화, 모노레포 지원, 헬스 체크로 worktree를 생성, 전환, 정리할 수 있습니다.
 
+### 왜 "copse"인가요?
+
+**Copse**는 나무 몇 그루가 옹기종기 모여 자라는 작은 숲을 뜻합니다. Git worktree는 브랜치를 별도의 작업 디렉토리로 체크아웃한 것 — 각각이 하나의 *나무(tree)*입니다. 하나의 레포에서 여러 worktree를 관리한다면, 그건 작은 숲을 가꾸는 것과 같습니다. 그게 바로 copse입니다.
+
 ## 주요 기능
 
 - **TUI 모드** — 인터랙티브 터미널 UI (`copse`)
@@ -278,6 +282,8 @@ copse init --skill claude-code
 ```bash
 copse add feature/login                        # 필요하면 브랜치를 만들고 worktree 생성
 copse add feature/login --base main            # 새 브랜치는 main에서 시작
+copse add feature/login --base origin/main     # origin/main 을 자동 fetch 후 분기 (아래 참고)
+copse add feature/login --base origin/main --no-fetch  # 자동 fetch 건너뛰기
 copse add existing-branch                      # 기존 브랜치로 worktree 생성
 
 # 모노레포: 포커스 패키지와 함께 생성
@@ -292,6 +298,33 @@ copse add --pr 123
 copse add --pr 456 --template review
 ```
 
+#### Remote 인식 base + 자동 fetch
+
+`--base` (또는 config 의 `defaults.base`) 값이 `<remote>/<branch>` 패턴이고 `<remote>` 가 실제로 등록된
+git remote 이면, `copse add` 는 worktree 를 만들기 전에 `git fetch <remote> <branch>` 를 먼저 실행합니다.
+stale 한 remote-tracking ref 에서 실수로 분기하는 걸 막아줍니다.
+
+- `--base main`, `--base develop`, `--base HEAD`, `--base <sha>` → fetch 없음 (local ref).
+- `--base origin/main`, `--base upstream/release/v2` → 해당 브랜치만 fetch 후 분기.
+- `--base fork/main` 인데 `fork` 가 등록된 remote 가 아님 → local ref 로 취급 (fetch 없음).
+- Fetch 실패 (오프라인, 인증 오류 등) 시 경고만 출력하고 local copy 로 계속 진행합니다.
+- 대상 브랜치가 이미 로컬에 존재하면 자동 fetch 는 건너뜁니다 (`--base` 는 새 브랜치에만 의미).
+
+`--no-fetch` 로 자동 fetch 를 강제로 건너뛸 수 있습니다. 매번 `copse add` 에서 remote-aware base 를
+기본으로 하고 싶으면 `defaults.base` 를 설정하세요:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "base": "origin/main"
+  }
+}
+```
+
+Base 우선순위 (높은 쪽이 이김): `--base` 플래그 → `template.base` → repo 별 `repos[].base` →
+`defaults.base` → git `HEAD`.
+
 ### `copse doctor`
 
 ```bash
@@ -652,6 +685,7 @@ copse: created default config at /Users/you/.config/copse/config.json
 | `linkFiles` | `string[]` | `[]` | 심볼릭 링크할 파일/디렉토리 (디스크 절약) |
 | `postCreate` | `string[]` | `[]` | worktree 생성 후 실행할 커맨드 |
 | `postRemove` | `string[]` | `[]` | worktree 제거 전 실행할 커맨드 |
+| `base` | `string` | — | 새 브랜치의 기본 base ref. 값이 등록된 remote 의 `<remote>/<branch>` 형태이면 `copse add` 가 `git fetch <remote> <branch>` 를 자동 실행 |
 
 #### `repos[]`
 
@@ -665,6 +699,7 @@ copse: created default config at /Users/you/.config/copse/config.json
 | `linkFiles` | `string[]` | 아니오 | 기본 링크 파일 오버라이드 |
 | `postCreate` | `string[]` | 아니오 | 기본 postCreate 훅 오버라이드 |
 | `postRemove` | `string[]` | 아니오 | 기본 postRemove 훅 오버라이드 |
+| `base` | `string` | 아니오 | 기본 base ref 오버라이드 |
 | `monorepo` | `object` | 아니오 | 모노레포 지원 설정 |
 
 #### `workspaces[]`

package/README.md

@@ -10,6 +10,10 @@
 
 Manage git worktrees with ease. Create, switch, and clean up worktrees with config-driven automation, monorepo support, and built-in health checks.
 
+### Why "copse"?
+
+A **copse** is a small group of trees growing closely together. Git worktrees are branches checked out as separate working directories — each one a *tree*. When you manage multiple worktrees for a single repo, you're tending a little grove. That's a copse.
+
 ## Features
 
 - **TUI mode** — interactive terminal UI (`copse`)
@@ -295,6 +299,8 @@ Every commit runs `validateConfig` before writing. Invalid input surfaces as an
 ```bash
 copse add feature/login                        # Create branch if needed + worktree
 copse add feature/login --base main            # New branches start from main
+copse add feature/login --base origin/main     # Auto-fetches origin/main first (see below)
+copse add feature/login --base origin/main --no-fetch  # Skip auto-fetch
 copse add existing-branch                      # Worktree for existing branch
 
 # Monorepo: create with focus packages
@@ -309,6 +315,33 @@ copse add --pr 123
 copse add --pr 456 --template review
 ```
 
+#### Remote-aware base + auto-fetch
+
+When `--base` (or `defaults.base` in config) matches `<remote>/<branch>` and `<remote>` is a
+known git remote, `copse add` runs `git fetch <remote> <branch>` before creating the worktree.
+This prevents accidentally branching from a stale local copy of a remote-tracking ref.
+
+- `--base main`, `--base develop`, `--base HEAD`, `--base <sha>` → no fetch (local ref).
+- `--base origin/main`, `--base upstream/release/v2` → fetch that specific branch, then branch from it.
+- `--base fork/main` when `fork` is not a configured remote → treated as a local ref (no fetch).
+- Fetch failures (offline, auth errors) print a warning and continue with the local copy.
+- Auto-fetch is skipped when the target branch already exists locally (`--base` only matters for new branches).
+
+Pass `--no-fetch` to skip the auto-fetch unconditionally. Set `defaults.base` to make
+remote-aware base the default for every `copse add`:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "base": "origin/main"
+  }
+}
+```
+
+Base resolution order (highest wins): `--base` flag → `template.base` → per-repo
+`repos[].base` → `defaults.base` → git `HEAD`.
+
 ### `copse doctor`
 
 ```bash
@@ -669,6 +702,7 @@ All repos inherit these unless overridden.
 | `linkFiles`   | `string[]` | `[]`                               | Files/dirs to symlink (saves disk)      |
 | `postCreate`  | `string[]` | `[]`                               | Commands to run after worktree creation |
 | `postRemove`  | `string[]` | `[]`                               | Commands to run before worktree removal |
+| `base`        | `string`   | —                                  | Default base ref for new branches. If it matches `<remote>/<branch>` of a known remote, `copse add` auto-runs `git fetch <remote> <branch>` first |
 
 #### `repos[]`
 
@@ -682,6 +716,7 @@ Per-repo overrides. Each entry requires `path`.
 | `linkFiles`   | `string[]` | No       | Override default link files         |
 | `postCreate`  | `string[]` | No       | Override default post-create hooks  |
 | `postRemove`  | `string[]` | No       | Override default post-remove hooks  |
+| `base`        | `string`   | No       | Override default base ref           |
 | `monorepo`    | `object`   | No       | Monorepo support config             |
 
 #### `workspaces[]`