worktree_manager 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1d77801499b0a0039a83fd38626cc70dd4ee886956457143eb184d855f893f7
+  data.tar.gz: 698b04a2042f8c441e462e47837d8290e812d7263b7fbd4bf6aee5879e91c294
+SHA512:
+  metadata.gz: 7d89c295082ad33003c03a1d07217a085c216706f63ff8078aef142f520b01ffb1e135eae8a422c39a7f17090747f20e02b7a90333f3983b15ac35c73b85cfae
+  data.tar.gz: 1df27c192fc56bf9a0e730f935b54e4a34aa2c30e436f64558f1c7f98819c23bf0045e782d46e6b38c659bb14d4b0bb4e04ba93a76bef1d1694e9179fad2509e

data/.github/workflows/test.yml

@@ -0,0 +1,52 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental }}
+    
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: ['3.1', '3.2', '3.3', '3.4']
+        experimental: [false]
+        include:
+          # Test on Windows with each Ruby version
+          - os: windows-latest
+            ruby: '3.1'
+            experimental: true
+          - os: windows-latest
+            ruby: '3.2'
+            experimental: true
+          - os: windows-latest
+            ruby: '3.3'
+            experimental: true
+          - os: windows-latest
+            ruby: '3.4'
+            experimental: true
+          # Test with Ruby head on Ubuntu
+          - os: ubuntu-latest
+            ruby: 'head'
+            experimental: true
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems
+    
+    - name: Run tests
+      run: bundle exec rspec --format documentation
+      continue-on-error: ${{ matrix.experimental }}

data/.gitignore

@@ -0,0 +1,37 @@
+# Ignore test and example directories
+tmp/
+
+# Ruby/Bundler files
+.bundle/
+vendor/bundle/
+
+# RSpec coverage
+coverage/
+
+# Local configuration
+.env
+.env.local
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Editor files
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# Log files
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+*.gem

data/.mise.toml

@@ -0,0 +1,9 @@
+[tools]
+ruby = "3.4.5"
+
+[env]
+_.file = [".env", ".env.local"]
+
+[tasks.release]
+run = "bash mise/release.sh"
+description = "Release a new version of the gem"

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.version

@@ -0,0 +1 @@
+0.2.1

data/.worktree.yml.example

@@ -0,0 +1,45 @@
+# Worktree Manager Configuration
+
+# Directory where worktrees will be created
+# When you run 'wm add feature', it creates at '../feature'
+worktrees_dir: "../"
+
+# Main branch name for 'wm reset' command
+# Change to "master" if your main branch is different
+main_branch_name: "main"
+
+# Hooks: Commands to run during worktree operations
+# Available environment variables:
+#   $WORKTREE_PATH - Worktree path (e.g., ../feature)
+#   $WORKTREE_BRANCH - Branch name
+#   $WORKTREE_MAIN - Main repository path
+#   $WORKTREE_ABSOLUTE_PATH - Full path to worktree
+#   $WORKTREE_FORCE - "true" if --force was used
+
+# Simple format (single command)
+# hooks:
+#   pre_add: "echo 'Creating worktree for $WORKTREE_BRANCH'"
+#   post_remove: "echo 'Removed $WORKTREE_PATH'"
+
+# Array format (multiple commands)
+# hooks:
+#   post_add:
+#     - "bundle install"
+#     - "cp .env.example .env"
+#     - "echo 'Setup complete!'"
+
+# Advanced format with options
+# hooks:
+#   post_add:
+#     commands:
+#       - "bundle install"
+#       - "yarn install"
+#       - "rake db:create db:migrate"
+#     pwd: "$WORKTREE_ABSOLUTE_PATH"  # Working directory (default: worktree for post_add)
+#     stop_on_error: false  # Continue even if a command fails (default: true)
+#   
+#   pre_remove:
+#     commands:
+#       - "git add -A"
+#       - "git stash push -m 'Auto-stash: $WORKTREE_BRANCH'"
+#     stop_on_error: false

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-07-23
+
+### Added
+- GitHub Actions CI/CD pipeline with Ruby 3.1-3.4 test matrix
+- Windows CI testing support for all Ruby versions
+- MIT LICENSE file
+- RubyGems metadata including MFA requirement
+- This CHANGELOG file
+
+### Changed
+- Minimum Ruby version requirement from 3.0 to 3.1
+- Updated gemspec to use `git ls-files` for better file inclusion
+- Fixed `wm reset` to always perform hard reset, preventing dirty working directory issues
+- Release script now updates Gemfile.lock to prevent version mismatch in CI
+
+### Fixed
+- CI failures caused by version mismatch between .version and Gemfile.lock
+- Reset command leaving uncommitted changes in working directory
+
+## [0.1.8] - 2025-07-21
+
+### Added
+- `wm init` command to initialize worktree configuration file
+- `wm reset` command to reset worktree branch to origin/main
+- Support for `--help` flag on all commands (e.g., `wm add --help`)
+
+### Changed
+- Refactored configuration example file from `.worktree.yml.sample` to `.worktree.yml.example`
+
+## [0.1.7] - 2025-07-21
+
+### Added
+- Interactive force removal prompt for worktrees with uncommitted changes
+
+## [0.1.6] - 2025-07-21
+
+### Added
+- `--no-hooks` option to skip hook execution during worktree operations
+- Comprehensive test coverage for main repository protection
+
+## Previous versions
+
+Earlier versions were released to GitHub Packages only. This is the first public release to RubyGems.org.

data/CLAUDE.md

@@ -0,0 +1,17 @@
+## General Working Rules
+
+- **Follow development guidelines as the top priority.**
+- Unless specifically requested, think and respond in English.
+- Do not leave spaces in blank lines. Do not leave trailing spaces at the end of lines. Files must end with a newline character.
+- Test implemented code directly or write tests using TDD approach.
+- After completing work, run newly written tests or related tests.
+- Check changes since the last commit using git before starting work.
+- Look for similar implementations in the project first, and check with gh if related issues or PRs are mentioned.
+- New features and tests should be written with minimal code, and do not make modifications beyond what was directly requested.
+
+## Not Goals
+
+Do not perform the following tasks unless explicitly requested:
+
+- Code refactoring work
+- Project configuration or structure changes

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'thor', '~> 1.0'
+gem 'tty-prompt', '~> 0.23'

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    worktree_manager (0.2.1)
+      thor (~> 1.0)
+      tty-prompt (~> 0.23)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    rake (13.3.0)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    thor (1.3.2)
+    tty-color (0.6.0)
+    tty-cursor (0.7.1)
+    tty-prompt (0.23.1)
+      pastel (~> 0.8)
+      tty-reader (~> 0.8)
+    tty-reader (0.9.0)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      wisper (~> 2.0)
+    tty-screen (0.8.2)
+    wisper (2.0.1)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  thor (~> 1.0)
+  tty-prompt (~> 0.23)
+  worktree_manager!
+
+BUNDLED WITH
+   2.6.9

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2025 nacyot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,391 @@
+# WorktreeManager
+
+A Ruby gem for managing Git worktrees with ease. WorktreeManager provides a simple and intuitive interface for creating, managing, and removing Git worktrees with built-in hook support.
+
+## Features
+
+- **Easy worktree management**: Create, list, and remove Git worktrees
+- **Branch operations**: Create new branches or checkout existing ones
+- **Hook system**: Execute custom scripts before/after worktree operations
+- **Conflict detection**: Automatic validation to prevent path and branch conflicts
+- **CLI interface**: Simple command-line tool for quick operations
+- **Ruby API**: Programmatic access for integration with other tools
+- **Configuration initialization**: Easy setup with `wm init` command
+- **Branch reset**: Reset worktree branches to origin/main with `wm reset`
+- **Help support**: All commands support `--help` flag for usage information
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'worktree_manager'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install worktree_manager
+```
+
+## Usage
+
+### Command Line Interface
+
+WorktreeManager provides a CLI tool called `wm` for managing worktrees:
+
+```bash
+# Initialize configuration file
+wm init
+
+# List all worktrees
+wm list
+
+# Create a new worktree using just a name (uses worktrees_dir)
+wm add feature-branch
+
+# Create a worktree with a relative path
+wm add ../feature-branch
+
+# Create a worktree with an absolute path
+wm add /path/to/feature-branch
+
+# Create a worktree with an existing branch
+wm add feature-branch existing-branch
+
+# Create a worktree with a new branch
+wm add feature-branch -b new-feature-branch
+
+# Remove a worktree using just a name
+wm remove feature-branch
+
+# Remove a worktree with a path
+wm remove ../feature-branch
+
+# Force operations (bypass safety checks)
+wm add existing-dir -f
+wm remove worktree-with-changes -f
+
+# Track remote branches
+wm add pr-154 -t origin/pr-154        # Create local pr-154 tracking origin/pr-154
+wm add pr-154 origin/pr-154           # Auto-detect remote branch
+wm add hotfix -t upstream/hotfix-123  # Track from different remote
+
+# Reset worktree branch to origin/main (must be run from worktree)
+wm reset                              # Reset current branch to origin/main
+wm reset -f                           # Force reset (discard uncommitted changes)
+
+# Get help for any command
+wm --help                             # Show all commands
+wm add --help                         # Show help for add command
+wm remove -h                          # Short help flag also works
+```
+
+#### Working with Remote Branches
+
+WorktreeManager makes it easy to work with remote branches:
+
+```bash
+# Method 1: Using --track (-t) option
+wm add pr-154 -t origin/pr-154
+# This will:
+# 1. Fetch origin/pr-154
+# 2. Create a new local branch 'pr-154' tracking 'origin/pr-154'
+# 3. Create worktree at '../worktrees/pr-154' (or configured location)
+
+# Method 2: Auto-detection (when branch name contains '/')
+wm add pr-154 origin/pr-154
+# Automatically detects that origin/pr-154 is a remote branch
+
+# Method 3: Different local and remote names
+wm add my-fix -t origin/pr-154
+# Creates local branch 'my-fix' tracking 'origin/pr-154'
+
+# Working with different remotes
+wm add upstream-fix -t upstream/fix-123
+wm add fork-feature -t fork/new-feature
+```
+
+Example workflow for Pull Request review:
+
+```bash
+# Review PR #154
+wm add pr-154 -t origin/pr-154
+cd ../worktrees/pr-154
+# Make changes, test, etc.
+
+# When done, remove the worktree
+cd ../main-repo
+wm remove pr-154
+```
+
+### Ruby API
+
+```ruby
+require 'worktree_manager'
+
+# Create a manager instance
+manager = WorktreeManager.new
+
+# List existing worktrees
+worktrees = manager.list
+worktrees.each do |worktree|
+  puts "Path: #{worktree.path}"
+  puts "Branch: #{worktree.branch}"
+  puts "Detached: #{worktree.detached?}"
+end
+
+# Add a new worktree
+worktree = manager.add("../feature-branch", "feature-branch")
+
+# Add a worktree with a new branch
+worktree = manager.add_with_new_branch("../new-feature", "new-feature-branch")
+
+# Remove a worktree
+manager.remove("../feature-branch")
+
+# Clean up removed worktrees
+manager.prune
+```
+
+## Hook System
+
+WorktreeManager supports hooks that execute before and after worktree operations:
+
+### Hook Types
+
+- `pre_add`: Execute before creating a worktree
+- `post_add`: Execute after creating a worktree
+- `pre_remove`: Execute before removing a worktree
+- `post_remove`: Execute after removing a worktree
+
+### Configuration
+
+Create a `.worktree.yml` file in your repository root to configure WorktreeManager:
+
+```yaml
+# Base directory for worktrees (default: "../")
+# When you run 'wm add feature', it creates worktree at '../feature' by default
+# With worktrees_dir set to "../worktrees", it creates at '../worktrees/feature'
+worktrees_dir: "../worktrees"
+
+# Main branch name for reset command (default: "main")
+# Used by 'wm reset' to determine which branch to reset to
+main_branch_name: "main"  # or "master" for older repositories
+
+# Hook configuration (see below)
+hooks:
+  # ...
+```
+
+#### Worktrees Directory
+
+The `worktrees_dir` option allows you to specify a default location for your worktrees:
+
+- **Default value**: `../` (parent directory of your main repository)
+- **Purpose**: Organize all worktrees in a specific directory
+- **Usage**: When you use `wm add <name>` with just a name (no path), it creates the worktree in `<worktrees_dir>/<name>`
+
+Example configurations:
+
+```yaml
+# Keep worktrees in a sibling directory
+worktrees_dir: "../worktrees"
+
+# Keep worktrees in a subdirectory of the parent
+worktrees_dir: "../../git-worktrees"
+
+# Use absolute path
+worktrees_dir: "/home/user/projects/worktrees"
+```
+
+### Hook Configuration
+
+Hooks allow you to execute custom scripts during worktree operations:
+
+```yaml
+hooks:
+  # Execute before creating a worktree (runs in main repository)
+  pre_add:
+    commands:
+      - "echo 'Creating worktree at: $WORKTREE_PATH'"
+      - "echo 'Branch: $WORKTREE_BRANCH'"
+    stop_on_error: true  # Stop if any command fails (default: true)
+
+  # Execute after creating a worktree (runs in new worktree directory)
+  post_add:
+    commands:
+      - "bundle install"
+      - "echo 'Setup complete: $WORKTREE_BRANCH'"
+    # Override default working directory if needed
+    # pwd: "$WORKTREE_MAIN"  # Run in main repository instead
+
+  # Execute before removing a worktree (runs in worktree directory)
+  pre_remove:
+    commands:
+      - "git add -A"
+      - "git stash push -m 'Auto stash before removal'"
+    stop_on_error: false  # Continue even if commands fail
+
+  # Execute after removing a worktree (runs in main repository)
+  post_remove:
+    commands:
+      - "echo 'Cleanup complete: $WORKTREE_PATH'"
+```
+
+### Available Environment Variables
+
+- `$WORKTREE_PATH`: Path where the worktree will be created/removed (relative path)
+- `$WORKTREE_ABSOLUTE_PATH`: Absolute path to the worktree
+- `$WORKTREE_BRANCH`: Branch name (if specified)
+- `$WORKTREE_MAIN`: Main repository path
+- `$WORKTREE_MANAGER_ROOT`: Main repository path (legacy, same as `$WORKTREE_MAIN`)
+- `$WORKTREE_FORCE`: Whether force option is enabled ("true" or "")
+- `$WORKTREE_SUCCESS`: Whether the operation succeeded (post hooks only, "true" or "false")
+
+### Practical Hook Examples
+
+```yaml
+hooks:
+  # Automatic development environment setup
+  post_add:
+    commands:
+      - "bundle install"              # Install dependencies
+      - "yarn install"                # Install JS dependencies
+      - "cp .env.example .env"        # Copy environment variables
+      - "code ."                      # Open in VS Code
+    # Default pwd is the new worktree directory
+
+  # Automatic backup of work
+  pre_remove:
+    commands:
+      - "git add -A"
+      - "git stash push -m 'Auto backup: $WORKTREE_BRANCH'"
+    stop_on_error: false  # Continue even if nothing to stash
+
+  # Notification system (run in main repository)
+  post_add:
+    commands:
+      - "osascript -e 'display notification \"Workspace ready: $WORKTREE_BRANCH\" with title \"WorktreeManager\"'"
+    pwd: "$WORKTREE_MAIN"  # Run notification from main repo
+
+  # CI/CD integration
+  post_add:
+    commands:
+      - "gh pr create --draft --title 'WIP: $WORKTREE_BRANCH' --body 'Auto-created by worktree manager'"
+    pwd: "$WORKTREE_ABSOLUTE_PATH"
+```
+
+## CLI Command Reference
+
+All commands support help flags (`--help`, `-h`, `-?`, `--usage`) to display usage information.
+
+### `wm version`
+Display the current installed version.
+
+### `wm init`
+Initialize a `.worktree.yml` configuration file in your repository.
+
+**Options**:
+- `-f, --force`: Overwrite existing configuration file
+
+**Requirements**: Must be run from the main Git repository
+
+**Examples**:
+```bash
+wm init                                  # Create .worktree.yml from example
+wm init --force                          # Overwrite existing .worktree.yml
+```
+
+### `wm list`
+List all worktrees in the current Git repository. Can be run from either the main repository or any worktree.
+
+### `wm add PATH [BRANCH]`
+Create a new worktree.
+
+**Arguments**:
+- `PATH`: Path where the worktree will be created
+- `BRANCH`: Branch to use (optional)
+
+**Options**:
+- `-b, --branch BRANCH`: Create a new branch for the worktree
+- `-f, --force`: Force creation even if directory exists
+- `-v, --verbose`: Enable verbose output for debugging
+
+**Examples**:
+```bash
+wm add ../feature-api feature/api        # Use existing branch
+wm add ../new-feature -b feature/new     # Create new branch
+wm add ../override --force               # Force creation
+```
+
+### `wm remove PATH`
+Remove an existing worktree.
+
+**Arguments**:
+- `PATH`: Path of the worktree to remove
+
+**Options**:
+- `-f, --force`: Force removal even if worktree has changes
+- `-v, --verbose`: Enable verbose output for debugging
+
+**Examples**:
+```bash
+wm remove ../feature-api                 # Normal removal
+wm remove ../old-feature --force         # Force removal
+```
+
+### `wm reset`
+Reset the current worktree branch to origin/main (or configured main branch).
+
+**Options**:
+- `-f, --force`: Force reset even if there are uncommitted changes
+
+**Requirements**: Must be run from a worktree (not from the main repository)
+
+**Configuration**: The target branch can be configured via `main_branch_name` in `.worktree.yml`
+
+**Examples**:
+```bash
+wm reset                                 # Reset to origin/main
+wm reset --force                         # Force reset, discarding changes
+```
+
+## Requirements
+
+- Ruby 3.0.0 or higher
+- Git 2.5.0 or higher (for worktree support)
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Build gem
+gem build worktree_manager.gemspec
+
+# Install locally
+gem install worktree_manager-*.gem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nacyot/worktree_manager.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request