{"id":46984807,"url":"https://github.com/halyph/worktree-script","last_synced_at":"2026-03-11T13:32:07.765Z","repository":{"id":319077566,"uuid":"1077502882","full_name":"halyph/worktree-script","owner":"halyph","description":"Git Worktree Automation Script","archived":false,"fork":false,"pushed_at":"2025-10-16T17:26:48.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T13:08:17.567Z","etag":null,"topics":["genai","generated"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halyph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-16T10:40:05.000Z","updated_at":"2025-10-16T17:26:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"25e9120a-5df2-4762-a848-28b104238d6b","html_url":"https://github.com/halyph/worktree-script","commit_stats":null,"previous_names":["halyph/worktree-script"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/halyph/worktree-script","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fworktree-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fworktree-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fworktree-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fworktree-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halyph","download_url":"https://codeload.github.com/halyph/worktree-script/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fworktree-script/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30382673,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T12:49:11.341Z","status":"ssl_error","status_checked_at":"2026-03-11T12:46:41.342Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genai","generated"],"created_at":"2026-03-11T13:32:07.591Z","updated_at":"2026-03-11T13:32:07.756Z","avatar_url":"https://github.com/halyph.png","language":"Shell","readme":"# Git Worktree Automation Script\n\nAn automated git worktree creation and management system that creates worktrees in a structured directory outside your main project.\n\n## Features\n\n- 🚀 **One-command worktree creation**: `wt feature-1` creates and switches to the worktree\n- 📁 **Organized structure**: Worktrees stored in `{project}_worktrees/` directory\n- 🌿 **Smart branch handling**: Works with existing local/remote branches or creates new ones\n- ♻️ **Reuse existing worktrees**: Navigates to existing worktrees instead of failing\n- 🛡️ **Comprehensive error handling**: Clear messages for all edge cases\n- 🧹 **Easy cleanup**: Remove worktrees with `wt-remove` command\n\n## Installation\n\n### Method 1: Add to .zshrc (Recommended)\n\n1. Copy the contents of `git-worktree-automation.sh` to your `~/.zshrc` file:\n\n```bash\n# Add this to the end of your ~/.zshrc file\ncat git-worktree-automation.sh \u003e\u003e ~/.zshrc\n```\n\n2. Reload your shell:\n\n```bash\nsource ~/.zshrc\n```\n\n### Method 2: Source the script\n\n1. Place the script in a permanent location:\n\n```bash\ncp git-worktree-automation.sh ~/.config/git-worktree-automation.sh\n```\n\n2. Add this line to your `~/.zshrc`:\n\n```bash\nsource ~/.config/git-worktree-automation.sh\n```\n\n3. Reload your shell:\n\n```bash\nsource ~/.zshrc\n```\n\n### Method 3: Symlink (Best for Development)\n\nThis method is ideal if you want to keep the script in this repository and easily update it:\n\n1. Create a symlink to the script in a directory that's in your PATH or config directory:\n\n```bash\n# Option A: Link to a directory in your PATH (e.g., /usr/local/bin)\nln -s \"$(pwd)/git-worktree-automation.sh\" /usr/local/bin/git-worktree-automation.sh\n\n# Option B: Link to your config directory\nmkdir -p ~/.config\nln -s \"$(pwd)/git-worktree-automation.sh\" ~/.config/git-worktree-automation.sh\n```\n\n2. Add this line to your `~/.zshrc`:\n\n```bash\n# If you used Option A (PATH directory)\nsource /usr/local/bin/git-worktree-automation.sh\n\n# If you used Option B (config directory)\nsource ~/.config/git-worktree-automation.sh\n```\n\n3. Reload your shell:\n\n```bash\nsource ~/.zshrc\n```\n\n**Benefits of the symlink method:**\n- ✅ Easy updates - just `git pull` in this repository\n- ✅ Version control - track changes to your automation script\n- ✅ Portability - works across multiple machines with the same setup\n- ✅ Clean separation - keeps your `.zshrc` minimal\n\n## Usage\n\n### Basic Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `wt \u003cbranch-name\u003e` | Create/switch to worktree | `wt feature-1` |\n| `wt-list` | List all worktrees | `wt-list` |\n| `wt-remove \u003cbranch\u003e` | Remove a worktree | `wt-remove feature-1` |\n\n### Examples\n\n#### Creating Worktrees\n\n```bash\n# In project \"myproject\"\n\n# New branches (created from current HEAD)\nwt feature-1           # Creates myproject_worktrees/feature-1\nwt bugfix/issue-123    # Creates myproject_worktrees/bugfix/issue-123\nwt hotfix-2024         # Creates myproject_worktrees/hotfix-2024\n\n# Remote branches (after git fetch)\nwt feature/user-auth   # Creates from origin/feature/user-auth\nwt release/v2.1.0      # Creates from origin/release/v2.1.0\n\n# Existing local branches\nwt main                # Creates from local main branch\nwt develop             # Creates from local develop branch\n```\n\n#### Managing Worktrees\n\n```bash\n# List all worktrees\nwt-list\n\n# Output:\n# 📋 Git worktrees for myproject:\n#\n# 📁 feature-1: /Users/you/projects/myproject_worktrees/feature-1\n#    🌿 Branch: feature-1\n#    📝 Commit: a1b2c3d4\n#\n# 📁 main: /Users/you/projects/myproject\n#    🌿 Branch: main\n#    📝 Commit: e5f6g7h8\n\n# Remove a worktree\nwt-remove feature-1\n```\n\n## Working with Remote Branches\n\nThe script has **built-in support for remote branches**! This is perfect for team collaboration where you need to work on branches created by colleagues or switch between different remote branches quickly.\n\n### How Remote Branch Detection Works\n\nThe script automatically detects and handles remote branches in this priority order:\n\n1. **Local branch** (if exists) - `refs/heads/branch-name`\n2. **Remote branch** (if exists) - `refs/remotes/origin/branch-name`\n3. **New branch** (if neither exists) - Creates from current HEAD\n\n### Remote Branch Examples\n\n#### Working with Colleague's Branches\n\n```bash\n# Colleague pushed \"feature/user-authentication\" to origin\ngit fetch                                    # Get latest remote refs\nwt feature/user-authentication              # Creates worktree tracking origin/feature/user-authentication\n\n# Script output:\n# ✅ Found existing remote branch: origin/feature/user-authentication\n# ⚙️ Creating worktree at: myproject_worktrees/feature/user-authentication\n# ✅ Worktree created successfully from existing branch!\n# 🎉 Worktree setup complete!\n```\n\n#### Common Team Workflow Patterns\n\n```bash\n# Work on hotfixes\ngit fetch\nwt hotfix/critical-security-fix             # Creates from origin/hotfix/critical-security-fix\n\n# Review pull requests\ngit fetch\nwt feature/new-dashboard                     # Creates from origin/feature/new-dashboard\n\n# Work on release branches\ngit fetch\nwt release/v2.1.0                           # Creates from origin/release/v2.1.0\n\n# Handle complex branch names\ngit fetch\nwt bugfix/issue-1234-payment-gateway        # Creates from origin/bugfix/issue-1234-payment-gateway\n```\n\n### Prerequisites for Remote Branches\n\n**Important**: Remote branches must be visible locally before the script can use them.\n\n```bash\n# Always fetch first to see latest remote branches\ngit fetch\n\n# Or fetch from specific remote\ngit fetch origin\n\n# Verify remote branch exists\ngit branch -r | grep feature-name\n\n# Then use the script\nwt feature-name\n```\n\n### What Happens Behind the Scenes\n\nWhen you run `wt remote-branch-name`:\n\n1. **Detection Phase**:\n   ```bash\n   # Script checks in order:\n   git show-ref --verify --quiet \"refs/heads/remote-branch-name\"      # Local first\n   git show-ref --verify --quiet \"refs/remotes/origin/remote-branch-name\"  # Then remote\n   ```\n\n2. **Worktree Creation**:\n   ```bash\n   # For remote branches, git automatically:\n   git worktree add myproject_worktrees/remote-branch-name remote-branch-name\n   # This creates a local tracking branch automatically\n   ```\n\n3. **Automatic Tracking Setup**:\n   - Creates local `remote-branch-name` branch\n   - Sets up tracking to `origin/remote-branch-name`\n   - Ready for commits and pushes\n\n### Branch Priority Examples\n\nUnderstanding which branch the script will use:\n\n```bash\n# Scenario 1: Only remote branch exists\ngit branch -r | grep feature-x              # Shows: origin/feature-x\nwt feature-x                                # ✅ Uses origin/feature-x\n\n# Scenario 2: Both local and remote exist\ngit branch | grep feature-y                 # Shows: feature-y\ngit branch -r | grep feature-y              # Shows: origin/feature-y\nwt feature-y                                # ✅ Uses local feature-y (priority)\n\n# Scenario 3: Neither exists\nwt feature-z                                # ✅ Creates new branch from HEAD\n```\n\n### Team Collaboration Tips\n\n**Daily Workflow**:\n```bash\n# Morning routine - sync with team\ngit fetch\nwt feature/current-task                     # Work on your feature\n\n# Switch to review colleague's work\ngit fetch\nwt feature/colleague-task                   # Quick switch to review\n\n# Switch back to your work\nwt feature/current-task                     # Instantly back to your branch\n```\n\n**Multiple Remote Scenarios**:\n```bash\n# The script currently checks 'origin' remote\n# For other remotes, fetch them first:\ngit fetch upstream\ngit fetch fork\n\n# Then create local branch manually if needed:\ngit checkout -b upstream-feature upstream/feature-name\nwt upstream-feature                         # Now script can use local branch\n```\n\n### Troubleshooting Remote Branches\n\n**Branch not found**:\n```bash\n# ❌ Error: Branch 'feature-x' not found\ngit fetch                                   # Fetch latest remotes\ngit branch -r | grep feature               # Verify branch name\nwt feature-x                               # Try again\n```\n\n**Multiple remotes conflict**:\n```bash\n# If you have branches with same name on different remotes\ngit branch -r | grep feature-name          # See all remote versions\n\n# Create specific local branches:\ngit checkout -b feature-origin origin/feature-name\ngit checkout -b feature-upstream upstream/feature-name\n\n# Then use script:\nwt feature-origin                          # Uses your local branch\n```\n\n**Outdated remote references**:\n```bash\n# If remote branch was deleted but you still see it\ngit remote prune origin                    # Clean up stale references\ngit fetch                                  # Get fresh remote refs\n```\n\n## How It Works\n\n### Directory Structure\n\nWhen you run `wt feature-1` in a project called \"myproject\":\n\n```\nparent-directory/\n├── myproject/                    # Original project\n└── myproject_worktrees/          # Worktrees directory\n    ├── feature-1/                # Your new worktree\n    ├── bugfix-123/              # Another worktree\n    └── hotfix-2024/             # Yet another worktree\n```\n\n### Branch Handling Logic\n\nThe script intelligently handles different branch scenarios:\n\n1. **Existing Local Branch**: Creates worktree from local branch\n2. **Existing Remote Branch**: Creates worktree tracking the remote branch\n3. **New Branch**: Creates worktree with a new branch from current HEAD\n4. **Existing Worktree**: Navigates to the existing worktree directory\n\n### Safety Features\n\n- ✅ Validates git repository before proceeding\n- ✅ Checks for required parameters\n- ✅ Handles worktree creation failures gracefully\n- ✅ Prevents overwriting existing worktrees\n- ✅ Provides clear error messages and suggestions\n- ✅ Cleans up empty worktree directories after removal\n\n## Script Components\n\n### Main Functions\n\n- **`wt()`**: Core worktree creation function\n- **`wt-list()`**: Lists all worktrees with details\n- **`wt-remove()`**: Safely removes worktrees\n\n### Key Features Explained\n\n#### Smart Path Resolution\n```bash\n# Gets the git repository root, not current subdirectory\nlocal git_root=$(git rev-parse --show-toplevel)\nlocal current_dir=$(basename \"$git_root\")\n```\n\n#### Branch Detection\n```bash\n# Check local branches\ngit show-ref --verify --quiet \"refs/heads/$branch_name\"\n\n# Check remote branches\ngit show-ref --verify --quiet \"refs/remotes/origin/$branch_name\"\n```\n\n#### Safe Worktree Creation\n```bash\n# For existing branches\ngit worktree add \"$worktree_path\" \"$branch_name\"\n\n# For new branches\ngit worktree add -b \"$branch_name\" \"$worktree_path\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Error: \"Not in a git repository\"**\n- Make sure you're running the command from within a git repository\n- Run `git status` to verify you're in a git repo\n\n**Error: \"Failed to create worktree\"**\n- The branch might already be checked out in another worktree\n- Use `wt-list` to see existing worktrees\n- Try `wt-remove \u003cbranch\u003e` if the worktree exists but is problematic\n\n**Error: \"Worktree not found\"**\n- Use `wt-list` to see available worktrees\n- Check if you're in the correct git repository\n\n### Manual Cleanup\n\nIf something goes wrong, you can manually clean up:\n\n```bash\n# List all worktrees\ngit worktree list\n\n# Remove a problematic worktree\ngit worktree remove /path/to/worktree\n\n# Or force remove if needed\ngit worktree remove --force /path/to/worktree\n```\n\n## Requirements\n\n- Git 2.5+ (for `git worktree` support)\n- Bash or Zsh shell\n- Standard Unix utilities (basename, dirname, mkdir)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalyph%2Fworktree-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalyph%2Fworktree-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalyph%2Fworktree-script/lists"}