diff --git a/README.ja.md b/README.ja.md index 6b91dc8..84b0cb4 100644 --- a/README.ja.md +++ b/README.ja.md @@ -10,13 +10,13 @@ すべてのローカルブランチをコマンド 1 つでリモートの最新状態に追従させ、リモートでマージ・削除済みのブランチを片付ける [GitHub CLI](https://cli.github.com/) 拡張です。 -[`hub sync`](https://hub.github.com/hub-sync.1.html) を単体の拡張として移植したもので、hub から gh に移行した人に向いています。 +[`hub sync`](https://hub.github.com/hub-sync.1.html) を独自に再実装したもので、[hub](https://github.com/mislav/hub) から gh に移行した人に向いています。 ```console $ gh sync Updated branch main (was 3f2a1bc). Updated branch feature/login (was 9d04e7a). -Deleted branch fix/typo (was c81b2d5). +Deleted branch fix/typo (was c81b2d5, merged via #42). warning: 'wip/experiment' has 2 commits not in 'origin/wip/experiment'; not updated ``` @@ -26,55 +26,81 @@ warning: 'wip/experiment' has 2 commits not in 'origin/wip/experiment'; not upda gh extension install him0/gh-sync ``` -macOS・Linux・Windows・FreeBSD 向けにビルド済みバイナリを配布しているため、Go は不要です。 +[GitHub CLI](https://cli.github.com/) 2.0 以降と Git 2.23 以降が必要です。macOS・Linux・Windows・FreeBSD 向けにビルド済みバイナリを配布しているため、Go は不要です。 -```bash -# 最新リリースにアップグレードする -gh extension upgrade sync - -# バージョンを指定してインストールする -gh extension install him0/gh-sync --pin v0.5.0 -``` +アップグレードは `gh extension upgrade sync`、バージョンを指定してインストールするには `gh extension install him0/gh-sync --pin v0.5.0` を実行します。 ## 使い方 -git リポジトリの中で実行します。 - -```bash -gh sync -``` +git リポジトリの中で `gh sync` を実行します。 ### 動作 1. **main remote を決めます。** `--remote` で指定した remote、無ければ `upstream`、`github`、`origin` のうち最初に見つかったもの、どれも無ければ最初の remote を使います。fork に `upstream` を追加している場合は、親リポジトリと同期します。 2. `git fetch --prune` で **その remote を fetch します。** ローカルブランチが追跡しているほかの remote(fork の `origin` など)も一緒に fetch します。fetch できなかった remote を追跡するブランチは、警告を出してスキップします。 -3. [除外](#ブランチの除外)したものを除く **すべてのローカルブランチを** upstream と、upstream が無ければ main remote 上の同名のブランチと比較します。マージ済みかどうかは、常に main remote のデフォルトブランチに対して判定します。 +3. [除外](#ブランチの除外)したものを除く **すべてのローカルブランチを** upstream と、upstream が無ければ main remote 上の同名のブランチと比較します。 -| ローカルブランチ | 動作 | +| ローカルブランチ | gh-sync の動作 | | --- | --- | -| 遅れている | fast-forward する: `Updated branch (was ).` | -| 先行している | 残す: `warning: '' has 2 commits not in '/'; not updated` | -| 分岐している | 残す: `warning: '' has diverged from '/' (2 ahead, 1 behind); not updated` | -| upstream が削除済みで、全コミットがデフォルトブランチに含まれる | 削除する: `Deleted branch (was ).` | -| upstream が削除済みで、先頭がマージ済み pull request の head か、そのコミットのいずれかと一致する(squash や rebase でのマージ) | 削除する: `Deleted branch (was , merged via #).` | -| upstream が削除済みで、マージ済み pull request の head の上にコミットを追加している | 残す: `warning: '' was deleted on , but 2 commits were added after it was merged via #; not deleted` | -| upstream が削除済みで、それ以外 | 残す: `warning: '' was deleted on , but 1 commit is not in '' and no merged pull request matches it; not deleted` | +| 遅れている | fast-forward する | +| 先行している、または分岐している | 警告を出して残す | +| upstream が削除済みで、[マージ済み](#マージ済みのブランチ) | 削除する | +| upstream が削除済みだが、マージされていない | 警告を出して残す | | 最新、または remote に対応するブランチが無い | 何もしない | -更新・削除したブランチが無く、警告も出ず、[別の worktree](#別の-worktree) が理由でスキップしたブランチも無い場合は、stderr が端末であれば `Already up to date.` と表示します。 +### マージ済みのブランチ + +upstream が削除されたブランチは、次のどちらかに当てはまればマージ済みとみなします。 + +- 全コミットが main remote のデフォルトブランチに含まれる。 +- 先頭が、マージ済み pull request の head か、そのコミットのいずれかと一致する。squash や rebase でのマージと、pull request より遅れているブランチ(GitHub の「Update branch」や、ほかの場所からの push があった場合)がこれに当たります。どの pull request かはメッセージに出ます: `Deleted branch (was , merged via #).` + +マージ済み pull request の head の上にコミットを追加したブランチは残します。 + +pull request は `gh api graphql` で確認します。確認するのは各 pull request の最後の 100 コミットだけで、追加の fetch はしません。確認できなかった場合、その結果が必要なブランチは残します。[トラブルシューティング](#トラブルシューティング)を参照してください。 ### 安全性 - merge、rebase、強制更新、push は一切しません。ローカルにしか無いコミットを持つブランチは必ず残ります。 - 削除されうるのは、upstream を git が prune した(`[gone]`)ブランチだけです。upstream を一度も設定していないブランチや、upstream が fetch refspec の対象外のブランチ(single-branch クローン、`gh pr checkout` による `refs/pull//head`)は削除しません。 -- マージ済み pull request より遅れているブランチ(GitHub の「Update branch」や、ほかの場所からの push があった場合)も削除します。そのコミットはすべて pull request に含まれているためです。確認するのは pull request の最後の 100 コミットだけで、追加の fetch はしません。 -- マージ済み pull request は `gh api graphql` で 50 本ごとに 1 リクエストで確認します。確認できない場合(`gh` が未認証、GitHub 以外の remote、API エラー、30 秒のタイムアウト)は `... and pull requests couldn't be looked up; not deleted` と警告してブランチを残し、理由を `warning: couldn't look up merged pull requests: ` として一度だけ表示します。`~/.ssh/config` のホストエイリアスや `ssh.github.com` は `ssh -G` で解決します。 -- 削除するブランチをチェックアウト中の場合は、先にデフォルトブランチへ切り替えます(`Switched to branch ...`)。ローカルに無ければ main remote から作成します。 -- [別の worktree](#別の-worktree) でチェックアウトされているブランチは更新しません。削除するのは `--remove-worktrees` を付けたときだけで、先にその worktree を削除します。このオプションが無ければ worktree は削除せず、`--force` を使うこともありません。 +- 削除するブランチをチェックアウト中の場合は、先にデフォルトブランチへ切り替えます。ローカルに無ければ main remote から作成します。 +- [別の worktree](#別の-worktree) でチェックアウトされているブランチは更新しません。削除するのは `--remove-worktrees` を付けたときだけです。 +- 更新するのは**ローカル**のブランチだけです。fork を `upstream` と同期したあと、fork も更新するには push してください(例: `git push origin main`)。 + +## オプション + +| オプション | 説明 | +| --- | --- | +| `--dry-run` | ブランチも worktree も変更せずに `Would update branch ...` / `Would delete branch ...` / `Would remove worktree ...` を表示する。fetch は実行する | +| `--verbose` | 変更や検索を行う git・`gh` コマンドと、スキップしたブランチの note も stderr に表示する | +| `--remote=NAME` | `NAME` を main remote として使う | +| `--exclude=GLOB` | `GLOB` に一致するブランチには触れない。複数回指定可。[ブランチの除外](#ブランチの除外)を参照 | +| `--remove-worktrees` | 削除するブランチの worktree を削除してから、ブランチを削除する。ignore されているファイルも消える。[worktree の削除](#worktree-の削除)を参照 | +| `--color=WHEN` | `auto`(デフォルト)、`always`、`never` | +| `--version` | バージョンを表示する | +| `--help` | 使い方を表示する | + +gh-sync は位置引数を取りません。`gh sync dry-run`(`--` の付け忘れ)は同期せずにエラーになります。 + +### ブランチの除外 + +除外したブランチは fast-forward も削除もされません。パターンは `--exclude` と git config の `gh-sync.exclude` から読み込み、すべてを適用します。 + +```sh +git config --add gh-sync.exclude 'wip/*' # --global ですべてのリポジトリに適用 +gh sync --exclude='wip/*' --exclude=tmp +``` + +パターンはブランチ名全体に対して Go の [`path.Match`](https://pkg.go.dev/path#Match) で照合するため、`*` は `/` に一致しません。`wip/*` は `wip/foo` に一致しますが、`wip/foo/bar` には一致しません。 + +### 色と出力 -gh-sync が更新するのは**ローカル**のブランチだけです。fork を `upstream` と同期したあと、fork も更新するには push してください(例: `git push origin main`)。 +- **stdout**: ブランチの更新・削除・切り替えと、worktree の削除。 +- **stderr**: 警告、hint、note、エラー、`--verbose` の出力。端末のときは fetch の進捗も表示します。更新・削除したブランチが無く、警告も出ず、別の worktree が理由でスキップしたブランチも無ければ、`Already up to date.` も表示します。 +- **終了ステータス**: 実行できなかったときや、更新・削除・fetch に失敗したときは `1`。それ以外は、警告や note を出してスキップした場合を含めて `0` です。 +- **色**: 更新したブランチは緑、削除したブランチは赤、警告は黄、エラーは太字の赤です。`--color=auto` では stdout と stderr をそれぞれ端末のときだけ色付けし、空でない [`NO_COLOR`](https://no-color.org) があれば色を付けません。 -### 別の worktree +## 別の worktree 別の worktree でチェックアウトされているブランチは、git が移動も削除も拒否します。gh-sync はそのブランチをスキップし、最後にまとめて報告します。 @@ -89,15 +115,20 @@ note: 3 branches checked out in other worktrees are behind their upstream; not u - warning には、削除するはずだったブランチが並びます。main worktree の中にある worktree は main worktree からの相対パスで、それ以外は絶対パスで表示します。 - note は、fast-forward するはずだったブランチの数です。`--verbose` を付けると同じ形式の一覧も表示します。更新するには、その worktree で `git pull --ff-only` を実行してください。 -#### worktree の削除 +### worktree の削除 -`--remove-worktrees` を付けるか、`git config gh-sync.removeWorktrees true` を設定すると、削除するブランチの worktree を `git worktree remove` で削除してから、ブランチを削除します。 +`--remove-worktrees` を付けるか、`git config gh-sync.removeWorktrees true` を設定すると、削除するブランチの worktree を `git worktree remove` で削除してから、ブランチを削除します。`--force` は使いません。 ```console Removed worktree .claude/worktrees/eager-wiggling-moonbeam. Deleted branch feature/a (was 1a2b3c4, merged via #12). ``` +デフォルトで無効なのは、次の二つを防げないためです。 + +- **ignore されているファイルは確認なしに削除されます。** git が拒否するのは変更済みまたは未追跡のファイルがある場合だけなので、worktree にある ignore 対象の `.env` やビルド成果物は失われます。 +- **その worktree でシェルやエージェントのセッションが動いているかどうかは、gh-sync には分かりません。** 動いていれば、作業ディレクトリが無くなります。 + git が削除を拒否した worktree は、ブランチとともに残します。終了ステータスは `0` のままです。 ```console @@ -107,49 +138,10 @@ warning: 'feature/c' is checked out in /home/me/elsewhere/wt, which is locked; n それ以外の理由(submodule を含む worktree など)で拒否された場合は、`..., which couldn't be removed: ; not deleted` と表示します。 -デフォルトで無効なのは、次の二つを防げないためです。 - -- **ignore されているファイルは確認なしに削除されます。** git が拒否するのは変更済みまたは未追跡のファイルがある場合だけなので、worktree にある ignore 対象の `.env` やビルド成果物は失われます。 -- **その worktree でシェルやエージェントのセッションが動いているかどうかは、gh-sync には分かりません。** 動いていれば、作業ディレクトリが無くなります。 - -そのほか: - - フラグは設定より優先します。`--remove-worktrees=false` で、その実行だけ無効にできます。 - 遅れているだけのブランチの worktree と main worktree は削除しません。 - `--dry-run` では、`git status` とロックの有無をもとに `Would remove worktree .` または同じ警告を表示します。submodule など、予測できない拒否もあります。 -## オプション - -| オプション | 説明 | -| --- | --- | -| `--verbose` | 変更や検索を行う git・`gh` コマンドと、スキップしたブランチの note、別の worktree が理由で更新しなかったブランチの一覧を stderr に表示する | -| `--dry-run` | ブランチも worktree も変更せずに `Would update branch ...` / `Would delete branch ...` / `Would remove worktree ...` を表示する。fetch は実行する | -| `--remove-worktrees` | 削除するブランチの worktree を、git が拒否しない限り削除してから、ブランチを削除する。ignore されているファイルも消える。git config の `gh-sync.removeWorktrees` でも有効にできる。[worktree の削除](#worktree-の削除)を参照 | -| `--color=WHEN` | `auto`(デフォルト)、`always`、`never` | -| `--remote=NAME` | `NAME` を main remote として使う | -| `--exclude=GLOB` | `GLOB` に一致するブランチには触れない。複数回指定可。[ブランチの除外](#ブランチの除外)を参照 | -| `--version` | バージョンを表示する | -| `--help` | 使い方を表示する | - -gh-sync は位置引数を取りません。`gh sync dry-run`(`--` の付け忘れ)は同期せずにエラーになります。 - -### ブランチの除外 - -除外したブランチは fast-forward も削除もされません。パターンは `--exclude` と git config の `gh-sync.exclude` から読み込み、すべてを適用します。 - -```sh -git config --add gh-sync.exclude 'wip/*' # --global ですべてのリポジトリに適用 -gh sync --exclude='wip/*' --exclude=tmp -``` - -パターンはブランチ名全体に対して Go の [`path.Match`](https://pkg.go.dev/path#Match) で照合するため、`*` は `/` に一致しません。`wip/*` は `wip/foo` に一致しますが、`wip/foo/bar` には一致しません。 - -### 色と出力 - -更新したブランチは緑、削除したブランチは赤、警告は黄、エラーは太字の赤で表示します。`--color=auto` では stdout と stderr をそれぞれ端末のときだけ色付けし、空でない [`NO_COLOR`](https://no-color.org) があれば色を付けません。 - -ブランチの更新・削除・切り替えと worktree の削除は stdout に、警告、hint、note、エラー、`--verbose` の出力、fetch の進捗、`Already up to date.` は stderr に出力します(最後の二つは端末のときだけ)。終了ステータスは、実行できなかったときや更新・削除・fetch に失敗したときは `1`、それ以外(警告や note を出してスキップした場合を含む)は `0` です。 - ## トラブルシューティング **`could not determine default branch`** @@ -162,15 +154,10 @@ main remote に使える `HEAD`、`main`、`master` がありません。`git re `branch..merge` が無いか、不正です。`git branch --set-upstream-to=/ ` で直してください。 **`warning: couldn't look up merged pull requests: `** -確認できるようになるまで、コミットがデフォルトブランチに含まれないブランチは残ります。`gh auth status` を確認してください。GitHub 以外の remote は確認できません。 +`gh` が未認証か、remote が GitHub 上に無いか、API が失敗したか 30 秒以内に応答しませんでした。確認できるようになるまで、コミットがデフォルトブランチに含まれないブランチは `... and pull requests couldn't be looked up; not deleted` と警告して残します。`gh auth status` を確認してください。`~/.ssh/config` のホストエイリアスや `ssh.github.com` は `ssh -G` で解決します。 バグを報告するときは、`gh sync --version` と `gh sync --verbose` の出力を添えてください。 -## 必要なもの - -- [GitHub CLI](https://cli.github.com/) 2.0 以降 -- Git 2.23 以降 - ## 開発 ツールのバージョンとタスクは [mise](https://mise.jdx.dev/) で管理しています。 @@ -183,10 +170,6 @@ mise run lint # go vet、gofmt のチェック、golangci-lint `v*` タグを push するとリリースが公開されます。開発上の決まりは [CLAUDE.md](CLAUDE.md) を参照してください。 -## 謝辞 - -[hub](https://github.com/mislav/hub) の `sync` コマンドに着想を得て、GitHub CLI 向けに独自に再実装したものです。 - ## ライセンス [MIT](LICENSE) diff --git a/README.md b/README.md index 8d13dc1..5ceadfb 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,13 @@ English | [日本語](README.ja.md) A [GitHub CLI](https://cli.github.com/) extension that brings every local branch up to date with its remote in one command, and cleans up the branches that were merged and deleted there. -It is a standalone port of [`hub sync`](https://hub.github.com/hub-sync.1.html) for people who moved from hub to gh. +It is an independent reimplementation of [`hub sync`](https://hub.github.com/hub-sync.1.html) for people who moved from [hub](https://github.com/mislav/hub) to gh. ```console $ gh sync Updated branch main (was 3f2a1bc). Updated branch feature/login (was 9d04e7a). -Deleted branch fix/typo (was c81b2d5). +Deleted branch fix/typo (was c81b2d5, merged via #42). warning: 'wip/experiment' has 2 commits not in 'origin/wip/experiment'; not updated ``` @@ -26,55 +26,81 @@ warning: 'wip/experiment' has 2 commits not in 'origin/wip/experiment'; not upda gh extension install him0/gh-sync ``` -Precompiled binaries are published for macOS, Linux, Windows and FreeBSD, so Go is not required. +It needs [GitHub CLI](https://cli.github.com/) 2.0 or later and Git 2.23 or later. Precompiled binaries are published for macOS, Linux, Windows and FreeBSD, so Go is not required. -```bash -# Upgrade to the latest release -gh extension upgrade sync - -# Install a specific version -gh extension install him0/gh-sync --pin v0.5.0 -``` +Upgrade with `gh extension upgrade sync`, or install a specific version with `gh extension install him0/gh-sync --pin v0.5.0`. ## Usage -Run it anywhere inside a git repository: - -```bash -gh sync -``` +Run `gh sync` anywhere inside a git repository. ### What it does 1. **Picks the main remote**: the one given with `--remote`, otherwise the first of `upstream`, `github` and `origin` that exists, otherwise the first remote. In a fork with an `upstream` remote, your branches are synced with the parent repository. -2. **Fetches it** with `git fetch --prune`, together with every other remote a local branch tracks (such as your fork's `origin`). If one of those can't be fetched, the branches tracking it are skipped with a warning. -3. **Checks every local branch**, except [excluded](#excluding-branches) ones, against its upstream, or against the same-named branch on the main remote when it has none. Merges are always checked against the main remote's default branch. +2. **Fetches it** with `git fetch --prune`, together with every other remote a local branch tracks (such as your fork's `origin`). Branches tracking a remote that can't be fetched are skipped with a warning. +3. **Compares every local branch**, except [excluded](#excluding-branches) ones, with its upstream, or with the same-named branch on the main remote when it has none. -| Local branch | Action | +| Local branch | What gh-sync does | | --- | --- | -| Behind | Fast-forwarded: `Updated branch (was ).` | -| Ahead | Kept: `warning: '' has 2 commits not in '/'; not updated` | -| Diverged | Kept: `warning: '' has diverged from '/' (2 ahead, 1 behind); not updated` | -| Upstream deleted, all commits in the default branch | Deleted: `Deleted branch (was ).` | -| Upstream deleted, tip is the head or one of the commits of a merged pull request (squash or rebase merge) | Deleted: `Deleted branch (was , merged via #).` | -| Upstream deleted, commits added on top of a merged pull request's head | Kept: `warning: '' was deleted on , but 2 commits were added after it was merged via #; not deleted` | -| Upstream deleted, otherwise | Kept: `warning: '' was deleted on , but 1 commit is not in '' and no merged pull request matches it; not deleted` | +| Behind | Fast-forwards it | +| Ahead or diverged | Keeps it, with a warning | +| Upstream deleted, and [merged](#merged-branches) | Deletes it | +| Upstream deleted, but not merged | Keeps it, with a warning | | Up to date, or no counterpart on the remote | Nothing | -When no branch was updated or deleted, no warning was printed and no branch was skipped because of [another worktree](#other-worktrees), gh-sync prints `Already up to date.` to stderr if it is a terminal. +### Merged branches + +A branch whose upstream was deleted counts as merged when either is true: + +- All its commits are in the main remote's default branch. +- Its tip is the head, or one of the commits, of a merged pull request. This covers squash and rebase merges, and a branch that is behind its pull request (GitHub's "Update branch", a commit pushed from elsewhere). The message says which one: `Deleted branch (was , merged via #).` + +A branch with commits added on top of a merged pull request's head is kept. + +Pull requests are looked up with `gh api graphql`. Only the last 100 commits of each are checked, and nothing extra is fetched. If the lookup fails, the branches that depend on it are kept; see [Troubleshooting](#troubleshooting). ### Safety - gh-sync never merges, rebases, force-updates or pushes. A branch with local-only commits is always kept. - Only a branch whose upstream git pruned (`[gone]`) can be deleted. Branches that never had an upstream, or whose upstream is outside the fetch refspec (a single-branch clone, `refs/pull//head` from `gh pr checkout`), are never deleted. -- A branch that is behind its merged pull request (GitHub's "Update branch", a commit pushed from elsewhere) is deleted too: all its commits are in the pull request. Only the last 100 commits of a pull request are checked, and nothing extra is fetched. -- Merged pull requests are looked up with `gh api graphql`, one request per 50 branches. When that fails (`gh` not authenticated, a remote not on GitHub, an API error, a 30-second timeout), the branch is kept with `... and pull requests couldn't be looked up; not deleted`, and the reason is printed once as `warning: couldn't look up merged pull requests: `. SSH host aliases from `~/.ssh/config` and `ssh.github.com` are resolved with `ssh -G`. -- If the branch to delete is checked out, gh-sync first switches to the default branch (`Switched to branch ...`), creating it from the main remote if needed. -- A branch checked out in [another worktree](#other-worktrees) is never updated, and is deleted only with `--remove-worktrees`, which removes its worktree first. No worktree is removed without that option, and never with `--force`. +- If the branch to delete is checked out, gh-sync first switches to the default branch, creating it from the main remote if needed. +- A branch checked out in [another worktree](#other-worktrees) is never updated, and is deleted only with `--remove-worktrees`. +- Only **local** branches are updated. After syncing a fork against `upstream`, push to update the fork too (e.g. `git push origin main`). + +## Options + +| Option | Description | +| --- | --- | +| `--dry-run` | Print `Would update branch ...` / `Would delete branch ...` / `Would remove worktree ...` without changing any branch or worktree. The fetch still runs | +| `--verbose` | Also print, to stderr, the git and `gh` commands that change or look something up, and notes on skipped branches | +| `--remote=NAME` | Use `NAME` as the main remote | +| `--exclude=GLOB` | Leave branches matching `GLOB` alone. Repeatable. See [Excluding branches](#excluding-branches) | +| `--remove-worktrees` | Remove the worktree of a branch to delete, then delete the branch. Deletes ignored files. See [Removing worktrees](#removing-worktrees) | +| `--color=WHEN` | `auto` (default), `always` or `never` | +| `--version` | Print the version | +| `--help` | Print usage | + +gh-sync takes no positional arguments: `gh sync dry-run` (missing `--`) is rejected instead of running a sync. + +### Excluding branches + +Excluded branches are never fast-forwarded or deleted. Patterns come from `--exclude` and from the `gh-sync.exclude` git config key, and all of them apply: + +```sh +git config --add gh-sync.exclude 'wip/*' # add --global for every repository +gh sync --exclude='wip/*' --exclude=tmp +``` + +Patterns are matched against the whole branch name with Go's [`path.Match`](https://pkg.go.dev/path#Match), so `*` does not match `/`: `wip/*` matches `wip/foo` but not `wip/foo/bar`. + +### Color and output -gh-sync updates **local** branches only. After syncing a fork against `upstream`, push to update the fork too (e.g. `git push origin main`). +- **stdout**: branch updates, deletions and switches, and worktree removals. +- **stderr**: warnings, hints, notes, errors and `--verbose` output. When it is a terminal, also fetch progress, and `Already up to date.` if nothing was updated, deleted, warned about or skipped because of another worktree. +- **Exit status**: `1` when gh-sync could not run or an update, deletion or fetch failed. Otherwise `0`, including when branches were skipped with a warning or a note. +- **Color**: updated branches are green, deleted ones red, warnings yellow and errors bold red. With `--color=auto`, stdout and stderr are each colorized only when they are a terminal, and a non-empty [`NO_COLOR`](https://no-color.org) disables color. -### Other worktrees +## Other worktrees git refuses to move or delete a branch that is checked out in another worktree, so gh-sync skips it and reports the skipped branches together at the end: @@ -89,15 +115,20 @@ note: 3 branches checked out in other worktrees are behind their upstream; not u - The warning lists the branches that would have been deleted. A worktree inside the main worktree is shown relative to it, any other with its absolute path. - The note counts the branches that would have been fast-forwarded; `--verbose` lists them the same way. Update one with `git pull --ff-only` in its worktree. -#### Removing worktrees +### Removing worktrees -With `--remove-worktrees`, or `git config gh-sync.removeWorktrees true`, gh-sync removes the worktree of a branch it is about to delete with `git worktree remove`, then deletes the branch: +With `--remove-worktrees`, or `git config gh-sync.removeWorktrees true`, gh-sync removes the worktree of a branch it is about to delete with `git worktree remove`, never with `--force`, then deletes the branch: ```console Removed worktree .claude/worktrees/eager-wiggling-moonbeam. Deleted branch feature/a (was 1a2b3c4, merged via #12). ``` +It is off by default because of what it can't protect: + +- **Ignored files are deleted without asking.** git only refuses for modified or untracked files, so an ignored `.env` or build output in the worktree is lost. +- **gh-sync can't tell whether a shell or an agent session is still running in the worktree.** Its working directory disappears. + A worktree git refuses to remove is kept with its branch, and the exit status stays `0`: ```console @@ -107,49 +138,10 @@ warning: 'feature/c' is checked out in /home/me/elsewhere/wt, which is locked; n Any other refusal, such as a worktree with submodules, is reported as `..., which couldn't be removed: ; not deleted`. -It is off by default because of what it can't protect: - -- **Ignored files are deleted without asking.** git only refuses for modified or untracked files, so an ignored `.env` or build output in the worktree is lost. -- **gh-sync can't tell whether a shell or an agent session is still running in the worktree.** Its working directory disappears. - -Also: - - The flag overrides the config: `--remove-worktrees=false` turns it off for one run. - Worktrees of branches that are only behind are never removed, and neither is the main worktree. - `--dry-run` prints `Would remove worktree .` or the same warnings, from `git status` and the lock. It can't predict every refusal (submodules, for example). -## Options - -| Option | Description | -| --- | --- | -| `--verbose` | Print the git and `gh` commands that change or look something up to stderr, plus notes on skipped branches and the list of branches not updated because of another worktree | -| `--dry-run` | Print `Would update branch ...` / `Would delete branch ...` / `Would remove worktree ...` without changing any branch or worktree. The fetch still runs | -| `--remove-worktrees` | Remove the worktree of a branch to delete, unless git refuses, then delete the branch. Deletes ignored files. Also `gh-sync.removeWorktrees` in git config. See [Removing worktrees](#removing-worktrees) | -| `--color=WHEN` | `auto` (default), `always` or `never` | -| `--remote=NAME` | Use `NAME` as the main remote | -| `--exclude=GLOB` | Leave branches matching `GLOB` alone. Repeatable. See [Excluding branches](#excluding-branches) | -| `--version` | Print the version | -| `--help` | Print usage | - -gh-sync takes no positional arguments: `gh sync dry-run` (missing `--`) is rejected instead of running a sync. - -### Excluding branches - -Excluded branches are never fast-forwarded or deleted. Patterns come from `--exclude` and from the `gh-sync.exclude` git config key, and all of them apply: - -```sh -git config --add gh-sync.exclude 'wip/*' # add --global for every repository -gh sync --exclude='wip/*' --exclude=tmp -``` - -Patterns are matched against the whole branch name with Go's [`path.Match`](https://pkg.go.dev/path#Match), so `*` does not match `/`: `wip/*` matches `wip/foo` but not `wip/foo/bar`. - -### Color and output - -Updated branches are green, deleted ones red, warnings yellow and errors bold red. With `--color=auto`, stdout and stderr are each colorized only when they are a terminal, and a non-empty [`NO_COLOR`](https://no-color.org) disables color. - -Branch updates, deletions and switches and worktree removals go to stdout; warnings, hints, notes, errors, `--verbose` output, fetch progress and `Already up to date.` go to stderr, the last two only when it is a terminal. The exit status is `1` when gh-sync could not run or an update, deletion or fetch failed, and `0` otherwise, including when branches were skipped with a warning or a note. - ## Troubleshooting **`could not determine default branch`** @@ -162,15 +154,10 @@ Local changes in the checked-out branch would be overwritten. Commit or stash th `branch..merge` is missing or invalid. Fix it with `git branch --set-upstream-to=/ `. **`warning: couldn't look up merged pull requests: `** -Branches whose commits are not in the default branch are kept until the lookup works. Check `gh auth status`; a remote that is not on GitHub can't be looked up. +`gh` is not authenticated, the remote is not on GitHub, or the API failed or took more than 30 seconds. Branches whose commits are not in the default branch are kept, with `... and pull requests couldn't be looked up; not deleted`, until the lookup works. Check `gh auth status`. SSH host aliases from `~/.ssh/config` and `ssh.github.com` are resolved with `ssh -G`. When reporting a bug, please include the output of `gh sync --version` and `gh sync --verbose`. -## Requirements - -- [GitHub CLI](https://cli.github.com/) 2.0 or later -- Git 2.23 or later - ## Development Tool versions and tasks are managed with [mise](https://mise.jdx.dev/). @@ -183,10 +170,6 @@ mise run lint # go vet + gofmt check + golangci-lint Pushing a `v*` tag publishes a release. See [CLAUDE.md](CLAUDE.md) for the contribution rules. -## Acknowledgments - -Inspired by the `sync` command of [hub](https://github.com/mislav/hub), which this extension reimplements on its own for the GitHub CLI. - ## License [MIT](LICENSE)