Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 65 additions & 82 deletions README.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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 <name> (was <sha>).` |
| 先行している | 残す: `warning: '<name>' has 2 commits not in '<remote>/<branch>'; not updated` |
| 分岐している | 残す: `warning: '<name>' has diverged from '<remote>/<branch>' (2 ahead, 1 behind); not updated` |
| upstream が削除済みで、全コミットがデフォルトブランチに含まれる | 削除する: `Deleted branch <name> (was <sha>).` |
| upstream が削除済みで、先頭がマージ済み pull request の head か、そのコミットのいずれかと一致する(squash や rebase でのマージ) | 削除する: `Deleted branch <name> (was <sha>, merged via #<number>).` |
| upstream が削除済みで、マージ済み pull request の head の上にコミットを追加している | 残す: `warning: '<name>' was deleted on <remote>, but 2 commits were added after it was merged via #<number>; not deleted` |
| upstream が削除済みで、それ以外 | 残す: `warning: '<name>' was deleted on <remote>, but 1 commit is not in '<default>' 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 <name> (was <sha>, merged via #<number>).`

マージ済み 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/<N>/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: <reason>` として一度だけ表示します。`~/.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 はそのブランチをスキップし、最後にまとめて報告します。

Expand All @@ -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
Expand All @@ -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: <git のメッセージ>; not deleted` と表示します。

デフォルトで無効なのは、次の二つを防げないためです。

- **ignore されているファイルは確認なしに削除されます。** git が拒否するのは変更済みまたは未追跡のファイルがある場合だけなので、worktree にある ignore 対象の `.env` やビルド成果物は失われます。
- **その worktree でシェルやエージェントのセッションが動いているかどうかは、gh-sync には分かりません。** 動いていれば、作業ディレクトリが無くなります。

そのほか:

- フラグは設定より優先します。`--remove-worktrees=false` で、その実行だけ無効にできます。
- 遅れているだけのブランチの worktree と main worktree は削除しません。
- `--dry-run` では、`git status` とロックの有無をもとに `Would remove worktree <path>.` または同じ警告を表示します。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`**
Expand All @@ -162,15 +154,10 @@ main remote に使える `HEAD`、`main`、`master` がありません。`git re
`branch.<name>.merge` が無いか、不正です。`git branch --set-upstream-to=<remote>/<branch> <name>` で直してください。

**`warning: couldn't look up merged pull requests: <reason>`**
確認できるようになるまで、コミットがデフォルトブランチに含まれないブランチは残ります。`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/) で管理しています。
Expand All @@ -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)
Loading
Loading