easy-worktree 0.1.1__tar.gz → 0.1.3__tar.gz

{easy_worktree-0.1.1 → easy_worktree-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easy-worktree
-Version: 0.1.1
+Version: 0.1.3
 Summary: Git worktree を簡単に管理するための CLI ツール
 Project-URL: Homepage, https://github.com/igtm/easy-worktree
 Project-URL: Repository, https://github.com/igtm/easy-worktree
@@ -35,11 +35,11 @@ It keeps the root of your git repository as your primary working area (main), wh
 
 ### Key Features
 
-- **Standardized directory structure**: Worktrees are created in a `.worktrees/` subdirectory (configurable). Keeps your root directory clean.
-- **Auto Sync**: Automatically sync files ignored by git (like `.env`) from the root to each worktree.
+- **Smart Selection**: Quickly switch between worktrees with `wt select`. "Jump" into a new shell instantly without any special setup.
+- **Auto Setup**: Automatically copy files (like `.env`) and run hooks to prepare each worktree.
 - **Clear Status**: `wt list` shows worktree branches, their status (clean/dirty), and associated GitHub PRs in a beautiful table.
 - **Smart Cleanup**: Easily batch remove merged branches or old unused worktrees.
-- **Two-letter shortcuts**: Fast execution with shortcuts like `ad`, `ls`, `st`, `sy`, `cl`.
+- **Two-letter shortcuts**: Fast execution with shortcuts like `ad`, `ls`, `sl`, `su`, `st`, `cl`.
 
 ## Prerequisites
 
@@ -107,6 +107,14 @@ You can also specify a base branch:
 wt add feature-1 main
 ```
 
+#### Skip Setup
+
+If you want to create a worktree without running the automatic setup (file copy and hooks):
+
+```bash
+wt add feature-1 --skip-setup
+```
+
 #### List worktrees
 
 ```bash
@@ -123,6 +131,23 @@ Quickly stash your current changes and move them to a new worktree.
 wt stash feature-2
 ```
 
+#### Switch Worktree (shortcut: `sl`)
+
+```bash
+wt select feature-1
+```
+
+Running `wt select` will **automatically "jump"** you into the worktree directory by starting a new subshell.
+
+- **Prompt**: Shows a `(wt:feature-1)` indicator.
+- **Terminal Title**: Updates the window title to `wt:feature-1`.
+- **Tmux**: Updates the tmux window name to `wt:feature-1` if running inside tmux.
+
+To return to your original directory, simply type `exit` or press `Ctrl-D`.
+
+*   **Interactive Mode**: Running `wt select` without arguments opens an interactive picker using `fzf`.
+*   **Nesting Control**: If you are already in a `wt` subshell, it will warn you to avoid confusing nesting.
+
 #### PR Management
 
 Fetch a PR and create a worktree for it. (Requires `gh` CLI)
@@ -141,12 +166,63 @@ Removes the worktree and its directory.
 
 ### Useful Features
 
-#### Sync configuration files (shortcut: `sy`)
+#### Setup Worktree (shortcut: `su`)
 
-Sync files like `.env` that are not in git from the root to your worktrees.
+Initialize the current worktree by copying required files and running the `post-add` hook.
 
 ```bash
-wt sync .env
+wt setup
+```
+
+#### Visualization and External Tools
+
+When you switch to a worktree using `wt select`, the following features are automatically enabled:
+- **Terminal Title**: The window or tab title is updated to `wt:worktree-name`.
+- **Tmux**: If you are inside tmux, the window name is automatically renamed to `wt:worktree-name`.
+
+You can also use the `wt current` (or `cur`) command to display the current worktree name in external tools.
+
+##### Tmux Status Bar
+Add the following to your `.tmux.conf` to show the worktree name in your status line:
+```tmux
+set -g status-right "#(wt current) | %Y-%m-%d %H:%M"
+```
+
+##### Zsh / Bash Prompt
+You can customize your prompt using the `$WT_SESSION_NAME` environment variable.
+
+**Zsh (.zshrc)**:
+```zsh
+RPROMPT='${WT_SESSION_NAME:+"(wt:$WT_SESSION_NAME)"} '"$RPROMPT"
+```
+
+**Bash (.bashrc)**:
+```bash
+PS1='$(if [ -n "$WT_SESSION_NAME" ]; then echo "($WT_SESSION_NAME) "; fi)'$PS1
+```
+
+##### Starship
+Add a custom module to your `starship.toml`:
+```toml
+[custom.easy_worktree]
+command = "wt current"
+when = 'test -n "$WT_SESSION_NAME"'
+format = "via [$symbol$output]($style) "
+symbol = "🌳 "
+style = "bold green"
+```
+
+##### Powerlevel10k
+Integrate beautiful worktree indicators by adding a custom segment to `.p10k.zsh`:
+
+1. Add `easy_worktree` to `POWERLEVEL9K_LEFT_PROMPT_ELEMENTS`.
+2. Define the following function:
+```zsh
+function prompt_easy_worktree() {
+  if [[ -n $WT_SESSION_NAME ]]; then
+    p10k segment -f 255 -b 28 -i '🌳' -t "wt:$WT_SESSION_NAME"
+  fi
+}
 ```
 
 
@@ -166,10 +242,13 @@ Customize behavior in `.wt/config.toml`:
 
 ```toml
 worktrees_dir = ".worktrees"   # Directory where worktrees are created
-sync_files = [".env"]          # Files to auto-sync
-auto_copy_on_add = true         # Enable auto-sync on add
+setup_files = [".env"]          # Files to auto-copy during setup
 ```
 
+#### Local Configuration Override
+
+You can create `.wt/config.local.toml` to override settings locally. This file is automatically added to `.gitignore` and ignores `config.toml` settings.
+
 ## Hooks
 
 You can define scripts to run automatically after `wt add`.

easy_worktree-0.1.3/README.md

@@ -0,0 +1,237 @@
+![hero](hero.png)
+
+# easy-worktree
+
+A CLI tool for easy Git worktree management.
+
+[日本語版 README](README_ja.md)
+
+## Overview
+
+`easy-worktree` simplifies git worktree management.
+It keeps the root of your git repository as your primary working area (main), while managing other worktrees in a subdirectory (default: `.worktrees/`).
+
+### Key Features
+
+- **Smart Selection**: Quickly switch between worktrees with `wt select`. "Jump" into a new shell instantly without any special setup.
+- **Auto Setup**: Automatically copy files (like `.env`) and run hooks to prepare each worktree.
+- **Clear Status**: `wt list` shows worktree branches, their status (clean/dirty), and associated GitHub PRs in a beautiful table.
+- **Smart Cleanup**: Easily batch remove merged branches or old unused worktrees.
+- **Two-letter shortcuts**: Fast execution with shortcuts like `ad`, `ls`, `sl`, `su`, `st`, `cl`.
+
+## Prerequisites
+
+`easy-worktree` requires the following:
+
+- **Git**: 2.34 or higher recommended.
+- **GitHub CLI (gh)**: Required for PR features (`wt list --pr`, `wt pr add`, `wt clean --merged`). [Installation guide](https://cli.github.com/).
+
+## Installation
+
+```bash
+pip install easy-worktree
+```
+
+Or install the development version:
+
+```bash
+git clone https://github.com/igtm/easy-worktree.git
+cd easy-worktree
+pip install -e .
+```
+
+## Usage
+
+### Getting Started
+
+#### Clone a new repository
+
+```bash
+wt clone https://github.com/user/repo.git
+```
+
+This clones the repository and initializes `easy-worktree` configuration.
+
+#### Initialize an existing repository
+
+```bash
+cd my-repo/
+wt init
+```
+
+Initializes `easy-worktree` in the current repository. Your main repository stays at the project root.
+
+### Managing Worktrees
+
+#### Add a worktree (shortcut: `ad`)
+
+```bash
+wt add feature-1
+```
+
+This creates the following structure:
+
+```
+my-repo/ (main)
+  .worktrees/
+    feature-1/  # Your new worktree
+  .wt/
+  ...
+```
+
+You can also specify a base branch:
+
+```bash
+wt add feature-1 main
+```
+
+#### Skip Setup
+
+If you want to create a worktree without running the automatic setup (file copy and hooks):
+
+```bash
+wt add feature-1 --skip-setup
+```
+
+#### List worktrees
+
+```bash
+wt list
+wt list --pr  # Show PR information
+```
+
+
+#### Stash and Move (shortcut: `st`)
+
+Quickly stash your current changes and move them to a new worktree.
+
+```bash
+wt stash feature-2
+```
+
+#### Switch Worktree (shortcut: `sl`)
+
+```bash
+wt select feature-1
+```
+
+Running `wt select` will **automatically "jump"** you into the worktree directory by starting a new subshell.
+
+- **Prompt**: Shows a `(wt:feature-1)` indicator.
+- **Terminal Title**: Updates the window title to `wt:feature-1`.
+- **Tmux**: Updates the tmux window name to `wt:feature-1` if running inside tmux.
+
+To return to your original directory, simply type `exit` or press `Ctrl-D`.
+
+*   **Interactive Mode**: Running `wt select` without arguments opens an interactive picker using `fzf`.
+*   **Nesting Control**: If you are already in a `wt` subshell, it will warn you to avoid confusing nesting.
+
+#### PR Management
+
+Fetch a PR and create a worktree for it. (Requires `gh` CLI)
+
+```bash
+wt pr add 123    # Fetches PR #123 and creates 'pr@123' worktree
+```
+
+#### Remove a worktree
+
+```bash
+wt rm feature-1
+```
+
+Removes the worktree and its directory.
+
+### Useful Features
+
+#### Setup Worktree (shortcut: `su`)
+
+Initialize the current worktree by copying required files and running the `post-add` hook.
+
+```bash
+wt setup
+```
+
+#### Visualization and External Tools
+
+When you switch to a worktree using `wt select`, the following features are automatically enabled:
+- **Terminal Title**: The window or tab title is updated to `wt:worktree-name`.
+- **Tmux**: If you are inside tmux, the window name is automatically renamed to `wt:worktree-name`.
+
+You can also use the `wt current` (or `cur`) command to display the current worktree name in external tools.
+
+##### Tmux Status Bar
+Add the following to your `.tmux.conf` to show the worktree name in your status line:
+```tmux
+set -g status-right "#(wt current) | %Y-%m-%d %H:%M"
+```
+
+##### Zsh / Bash Prompt
+You can customize your prompt using the `$WT_SESSION_NAME` environment variable.
+
+**Zsh (.zshrc)**:
+```zsh
+RPROMPT='${WT_SESSION_NAME:+"(wt:$WT_SESSION_NAME)"} '"$RPROMPT"
+```
+
+**Bash (.bashrc)**:
+```bash
+PS1='$(if [ -n "$WT_SESSION_NAME" ]; then echo "($WT_SESSION_NAME) "; fi)'$PS1
+```
+
+##### Starship
+Add a custom module to your `starship.toml`:
+```toml
+[custom.easy_worktree]
+command = "wt current"
+when = 'test -n "$WT_SESSION_NAME"'
+format = "via [$symbol$output]($style) "
+symbol = "🌳 "
+style = "bold green"
+```
+
+##### Powerlevel10k
+Integrate beautiful worktree indicators by adding a custom segment to `.p10k.zsh`:
+
+1. Add `easy_worktree` to `POWERLEVEL9K_LEFT_PROMPT_ELEMENTS`.
+2. Define the following function:
+```zsh
+function prompt_easy_worktree() {
+  if [[ -n $WT_SESSION_NAME ]]; then
+    p10k segment -f 255 -b 28 -i '🌳' -t "wt:$WT_SESSION_NAME"
+  fi
+}
+```
+
+
+#### Cleanup (shortcut: `cl`)
+
+```bash
+wt clean --merged
+wt clean --closed  # Remove worktrees for closed (unmerged) PRs
+wt clean --days 30
+```
+
+
+
+### Configuration
+
+Customize behavior in `.wt/config.toml`:
+
+```toml
+worktrees_dir = ".worktrees"   # Directory where worktrees are created
+setup_files = [".env"]          # Files to auto-copy during setup
+```
+
+#### Local Configuration Override
+
+You can create `.wt/config.local.toml` to override settings locally. This file is automatically added to `.gitignore` and ignores `config.toml` settings.
+
+## Hooks
+
+You can define scripts to run automatically after `wt add`.
+Templates are created in `.wt/post-add` upon initialization.
+
+## License
+
+MIT License

easy_worktree-0.1.3/README_ja.md

@@ -0,0 +1,235 @@
+![hero](hero.png)
+
+# easy-worktree
+
+Git worktree を簡単に管理するための CLI ツール
+
+## 概要
+
+`easy-worktree` は git worktree の管理をシンプルにするためのツールです。
+リポジトリのルートディレクトリをそのままメインの作業場所（main）として使いつつ、他のブランチでの作業が必要な場合はサブディレクトリ（デフォルトでは `.worktrees/`）に worktree を作成して管理します。
+
+### 主な特徴
+
+- **スマートな切り替え**: `wt select` で作業ディレクトリを瞬時に切り替え。特別な設定なしで新しいシェルとして「ジャンプ」できます。
+- **自動セットアップ**: `.env` などのファイルをルートから各 worktree へ自動的にコピー・初期化できます。
+- **わかりやすい一覧表示**: `wt list` で worktree の一覧、ブランチ、状態（clean/dirty）、GitHub PR 情報を美しく表示します。
+- **スマートなクリーンアップ**: マージ済みのブランチや古い worktree を簡単に削除できるようになります。
+- **2文字ショートカット**: `ad`, `ls`, `sl`, `su`, `st`, `cl` といった短いコマンドで素早く操作できます。
+
+## 前提条件
+
+`easy-worktree` には以下が必要です：
+
+- **Git**: 2.34 以上を推奨します。
+- **GitHub CLI (gh)**: PR 関連機能（`wt list --pr`, `wt pr add`, `wt clean --merged`）を利用する場合に必要です。[インストール方法](https://cli.github.com/)。
+
+## インストール
+
+```bash
+pip install easy-worktree
+```
+
+または開発版をインストール:
+
+```bash
+git clone https://github.com/igtm/easy-worktree.git
+cd easy-worktree
+pip install -e .
+```
+
+## 使い方
+
+### リポジトリの準備
+
+#### 新しくクローンする場合
+
+```bash
+wt clone https://github.com/user/repo.git
+```
+
+リポジトリをクローンし、`easy-worktree` 用の初期設定を自動で行います。
+
+#### 既存のリポジトリで使い始める場合
+
+```bash
+cd my-repo/
+wt init
+```
+
+現在のディレクトリをメインリポジトリ（ルート）として `easy-worktree` を初期化します。既存のリポジトリ構成はそのまま維持されます。
+
+### worktree の操作
+
+#### worktree を追加 (ショートカット: `ad`)
+
+```bash
+wt add feature-1
+```
+
+これにより、以下のディレクトリ構成が作成されます：
+
+```
+my-repo/ (main)
+  .worktrees/
+    feature-1/  # ここが新しい worktree
+  .wt/
+  ...
+```
+
+既存のブランチを指定して作成することもできます：
+
+```bash
+wt add feature-1 main
+```
+
+#### セットアップをスキップする
+
+自動セットアップ（ファイルのコピーや hook の実行）を行わずに worktree を作成したい場合は、`--skip-setup` フラグを使用します：
+
+```bash
+wt add feature-1 --skip-setup
+```
+
+#### 一覧を表示 (ショートカット: `ls`)
+
+```bash
+wt list
+wt ls --pr   # GitHub の PR 情報もあわせて表示
+```
+
+
+#### スタッシュと移動 (ショートカット: `st`)
+
+現在の変更をスタッシュし、そのまま新しい worktree を作成して移動します。
+
+```bash
+wt stash feature-2
+```
+
+#### ワークツリーを切り替える (ショートカット: `sl`)
+
+```bash
+wt select feature-1
+```
+
+`wt select` を実行すると、そのワークツリーのディレクトリへ**自動的に「ジャンプ」**します（新しいシェルが起動します）。
+
+- **プロンプト**: `(wt:feature-1)` のように表示されます。
+- **ターミナルタイトル**: ウィンドウのタイトル（ターミナルのタブ名など）が `wt:feature-1` に更新されます。
+- **Tmux**: tmux 内で実行している場合、ウィンドウ名が `wt:feature-1` に更新されます。
+
+元のディレクトリに戻りたい場合は `exit` を実行するか `Ctrl-D` を押してください。
+
+※ すでに `wt` のサブシェル内にいる状態で再度実行すると、ネストを警告するメッセージが表示されます。ネストを避けるには一度 `exit` してから切り替えることをお勧めします。
+
+引数なしで実行すると `fzf` によるインタラクティブな選択が可能です。
+
+#### PR 管理
+
+GitHub の PR を取得して worktree を作成します（`gh` CLI が必要です）。
+
+```bash
+wt pr add 123    # PR #123 を取得し 'pr@123' という名前で worktree を作成
+```
+
+#### 削除
+
+```bash
+wt rm feature-1
+```
+
+ディレクトリごと worktree を削除します。
+
+### 便利な機能
+
+#### ワークツリーの初期化 (ショートカット: `su`)
+
+`.env` ファイルなどのコピーや `post-add` フックの実行を、現在のワークツリーに対して行います。
+
+```bash
+wt setup
+```
+
+#### 可視化と外部ツールとの連携
+
+`wt select` でワークツリーに切り替えた際、以下の機能が自動的に有効になります：
+- **ターミナルタイトル**: ウィンドウやタブのタイトルが `wt:ワークツリー名` に更新されます。
+- **Tmux**: tmux 内にいる場合、ウィンドウ名が自動的に `wt:ワークツリー名` に変更されます。
+
+また、`wt current` (または `cur`) コマンドを使って、外部ツールに現在のワークツリー情報を表示できます。
+
+##### Tmux ステータスバー
+`.tmux.conf` に以下を追加して、ステータスラインに常時表示できます。
+```tmux
+set -g status-right "#(wt current) | %Y-%m-%d %H:%M"
+```
+
+##### Zsh / Bash プロンプト
+環境変数 `$WT_SESSION_NAME` を利用してプロンプトをカスタマイズできます。
+
+**Zsh (.zshrc)**:
+```zsh
+RPROMPT='${WT_SESSION_NAME:+"(wt:$WT_SESSION_NAME)"} '"$RPROMPT"
+```
+
+**Bash (.bashrc)**:
+```bash
+PS1='$(if [ -n "$WT_SESSION_NAME" ]; then echo "($WT_SESSION_NAME) "; fi)'$PS1
+```
+
+##### Starship
+`starship.toml` にカスタムモジュールを追加します。
+```toml
+[custom.easy_worktree]
+command = "wt current"
+when = 'test -n "$WT_SESSION_NAME"'
+format = "via [$symbol$output]($style) "
+symbol = "🌳 "
+style = "bold green"
+```
+
+##### Powerlevel10k
+`.p10k.zsh` にカスタムセグメントを定義することで、綺麗に統合できます。
+
+1. `POWERLEVEL9K_LEFT_PROMPT_ELEMENTS` に `easy_worktree` を追加。
+2. 以下の関数を定義：
+```zsh
+function prompt_easy_worktree() {
+  if [[ -n $WT_SESSION_NAME ]]; then
+    p10k segment -f 255 -b 28 -i '🌳' -t "wt:$WT_SESSION_NAME"
+  fi
+}
+```
+
+
+#### クリーンアップ (ショートカット: `cl`)
+
+```bash
+wt clean --merged
+wt clean --closed  # クローズされた (未マージ) PRのworktreeを削除
+wt clean --days 30
+```
+
+
+### 設定
+
+`.wt/config.toml` で挙動をカスタマイズできます：
+
+```toml
+worktrees_dir = ".worktrees"   # worktree を作成するディレクトリ名
+setup_files = [".env"]          # 自動セットアップでコピーするファイル一覧
+```
+
+#### ローカル設定の上書き
+
+`.wt/config.local.toml` を作成すると、設定をローカルでのみ上書きできます。このファイルは自動的に `.gitignore` に追加され、リポジトリにはコミットされません。
+
+## Hook
+
+`wt add` の後に自動実行されるスクリプトを記述できます。
+テンプレートが `.wt/post-add` に作成されます。
+
+## ライセンス
+
+MIT License