{"id":36549653,"url":"https://github.com/satococoa/wtp","last_synced_at":"2026-01-31T20:05:22.840Z","repository":{"id":305918722,"uuid":"1009089036","full_name":"satococoa/wtp","owner":"satococoa","description":"🌳 A powerful Git worktree CLI tool with automated setup, branch tracking, and smart navigation","archived":false,"fork":false,"pushed_at":"2025-12-25T15:04:34.000Z","size":5219,"stargazers_count":266,"open_issues_count":11,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T14:16:50.767Z","etag":null,"topics":["cli","developer-tools","git","git-worktree","go","productivity","worktree"],"latest_commit_sha":null,"homepage":"https://dev.to/satococoa/wtp-a-better-git-worktree-cli-tool-4i8l","language":"Go","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/satococoa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-26T14:58:45.000Z","updated_at":"2026-01-11T19:23:48.000Z","dependencies_parsed_at":"2025-10-28T16:15:51.282Z","dependency_job_id":"3af15173-e2f3-4126-8770-cc66bef618bb","html_url":"https://github.com/satococoa/wtp","commit_stats":null,"previous_names":["satococoa/wtp"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/satococoa/wtp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satococoa%2Fwtp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satococoa%2Fwtp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satococoa%2Fwtp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satococoa%2Fwtp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/satococoa","download_url":"https://codeload.github.com/satococoa/wtp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satococoa%2Fwtp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28952586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T18:30:42.805Z","status":"ssl_error","status_checked_at":"2026-01-31T18:30:19.593Z","response_time":128,"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":["cli","developer-tools","git","git-worktree","go","productivity","worktree"],"created_at":"2026-01-12T06:31:28.349Z","updated_at":"2026-01-31T20:05:22.834Z","avatar_url":"https://github.com/satococoa.png","language":"Go","readme":"# wtp (Worktree Plus)\n\nA powerful Git worktree management tool that extends git's worktree\nfunctionality with automated setup, branch tracking, and project-specific hooks.\n\n## Features - Why wtp Instead of git-worktree?\n\n### 🚀 No More Path Gymnastics\n\n**git-worktree pain:**\n`git worktree add ../project-worktrees/feature/auth feature/auth` **wtp\nsolution:** `wtp add feature/auth`\n\nwtp automatically generates sensible paths based on branch names. Your\n`feature/auth` branch goes to `../worktrees/feature/auth` - no redundant typing,\nno path errors.\n\n### 🧹 Clean Branch Management\n\n**git-worktree pain:** Remove worktree, then manually delete the branch. Forget\nthe second step? Orphaned branches accumulate. **wtp solution:**\n`wtp remove --with-branch feature/done` - One command removes both\n\nKeep your repository clean. When a feature is truly done, remove both the\nworktree and its branch in one atomic operation. No more forgotten branches\ncluttering your repo.\n\n### 🛠️ Zero-Setup Development Environments\n\n**git-worktree pain:** Create worktree → Copy .env → Install deps → Run\nmigrations → Finally start coding **wtp solution:** Configure once in\n`.wtp.yml`, then every `wtp add` runs your setup automatically\n\n```yaml\nhooks:\n  post_create:\n    # Copy real files from the MAIN worktree into the NEW worktree\n    - type: copy\n      from: \".env\" # Allowed even if gitignored. 'from' is always relative to the MAIN worktree\n      to: \".env\" # Destination is relative to the NEW worktree\n\n    # Share directories between the MAIN and NEW worktree\n    - type: symlink\n      from: \".bin\"\n      to: \".bin\"\n\n    # Prefer explicit, single-step setup commands\n    - type: command\n      command: \"npm ci\" # Example for Node.js (replace with your build/deps tool)\n    - type: command\n      command: \"npm run db:setup\"\n    # Alternative: using make or a task runner\n    # - type: command\n    #   command: \"make bootstrap\"\n```\n\nPerfect for microservices, monorepos, or any project with complex setup\nrequirements.\n\n### 📍 Instant Worktree Navigation\n\n**git-worktree pain:** `cd ../../../worktrees/feature/auth` (if you remember the\npath) **wtp solution:** `wtp cd feature/auth` with tab completion\n\nJump between worktrees instantly. Use `wtp cd @` to return to your main\nworktree (or just `wtp cd`). No more terminal tab confusion.\n\n## Requirements\n\n- Git 2.17 or later (for worktree support)\n- One of the following operating systems:\n  - Linux (x86_64 or ARM64)\n  - macOS (Apple Silicon M1/M2/M3)\n- One of the following shells (for completion support):\n  - Bash (4+/5.x) with bash-completion v2\n  - Zsh\n  - Fish\n\n## Releases\n\nView all releases and changelogs:\n[GitHub Releases](https://github.com/satococoa/wtp/releases)\n\nLatest stable version:\n[See releases](https://github.com/satococoa/wtp/releases/latest)\n\n## Installation\n\n### Using Homebrew (macOS/Linux)\n\n```bash\nbrew install satococoa/tap/wtp\n```\n\n### Using Go\n\n```bash\ngo install github.com/satococoa/wtp/v2/cmd/wtp@latest\n```\n\n### Download Binary\n\nDownload the latest binary from\n[GitHub Releases](https://github.com/satococoa/wtp/releases):\n\n```bash\n# macOS (Apple Silicon)\ncurl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Darwin_arm64.tar.gz | tar xz\nsudo mv wtp /usr/local/bin/\n\n# Linux (x86_64)\ncurl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_x86_64.tar.gz | tar xz\nsudo mv wtp /usr/local/bin/\n\n# Linux (ARM64)\ncurl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_arm64.tar.gz | tar xz\nsudo mv wtp /usr/local/bin/\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/satococoa/wtp.git\ncd wtp\ngo build -o wtp ./cmd/wtp\nsudo mv wtp /usr/local/bin/  # or add to PATH\n```\n\n## Quick Start\n\n### Automatic Path Generation (Recommended)\n\n```bash\n# Create worktree from existing branch (local or remote)\n# → Creates worktree at ../worktrees/feature/auth\n# Automatically tracks remote branch if not found locally\nwtp add feature/auth\n\n# Create worktree with new branch\n# → Creates worktree at ../worktrees/feature/new-feature\nwtp add -b feature/new-feature\n\n# Create new branch from specific commit\n# → Creates worktree at ../worktrees/hotfix/urgent\nwtp add -b hotfix/urgent abc1234\n\n# Create new branch tracking a different remote branch\n# → Creates worktree at ../worktrees/feature/test with branch tracking origin/main\nwtp add -b feature/test origin/main\n\n# Remote branch handling examples:\n\n# Automatically tracks remote branch if not found locally\n# → Creates worktree tracking origin/feature/remote-only\nwtp add feature/remote-only\n\n# If branch exists in multiple remotes, shows helpful error:\n# Error: branch 'feature/shared' exists in multiple remotes: origin, upstream\n# Please specify the remote explicitly (e.g., --track origin/feature/shared)\nwtp add feature/shared\n\n# Explicitly specify which remote to track\nwtp add -b feature/shared upstream/feature/shared\n```\n\n### Management Commands\n\n```bash\n# List all worktrees\nwtp list\n\n# Example output:\n# PATH                      BRANCH           HEAD\n# ----                      ------           ----\n# @ (main worktree)*        main             c72c7800\n# feature/auth              feature/auth     def45678\n# ../project-hotfix         hotfix/urgent    abc12345\n\n# Remove worktree only (by worktree name)\nwtp remove feature/auth\nwtp remove --force feature/auth  # Force removal even if dirty\n\n# Remove worktree and its branch\nwtp remove --with-branch feature/auth              # Only if branch is merged\nwtp remove --with-branch --force-branch feature/auth  # Force branch deletion\n```\n\n## Configuration\n\nwtp uses `.wtp.yml` for project-specific configuration:\n\n```yaml\nversion: \"1.0\"\ndefaults:\n  # Base directory for worktrees (relative to project root)\n  base_dir: \"../worktrees\"\n\nhooks:\n  post_create:\n    # Copy gitignored files from main worktree to new worktree\n    # Note: 'from' is relative to main worktree, 'to' is relative to new worktree\n    # If 'to' is omitted, it defaults to the same value as 'from' (relative paths only)\n    - type: copy\n      from: \".env\" # Copy actual .env file (gitignored)\n      to: \".env\"\n\n    - type: copy\n      from: \".claude\" # Copy AI context file (gitignored)\n\n    # Share directories between the main and new worktree\n    - type: symlink\n      from: \".bin\"\n      to: \".bin\"\n\n    # Execute commands in the new worktree\n    - type: command\n      command: \"npm install\"\n      env:\n        NODE_ENV: \"development\"\n\n    - type: command\n      command: \"make db:setup\"\n      work_dir: \".\"\n```\n\n### Copy Hooks: Main Worktree Reference\n\nCopy hooks are designed to help you bootstrap new worktrees using files from\nyour main worktree (even if they are gitignored):\n\n- `from`: path is always resolved relative to the main worktree.\n- `to`: path is resolved relative to the newly created worktree (defaults to `from` if omitted; absolute `from` requires explicit `to`).\n- Supports files and directories, including entries ignored by Git (e.g.,\n  `.env`, `.claude`, `.cursor/`).\n\nExamples:\n\n```yaml\nhooks:\n  post_create:\n    # Copy local env and AI context from MAIN worktree into the new worktree\n    - type: copy\n      from: \".env\"\n      to: \".env\"\n\n    - type: copy\n      from: \".claude\"\n\n    # Directory copy also works\n    - type: copy\n      from: \".cursor/\"\n      to: \".cursor/\"\n```\n\nThis behavior applies regardless of where you run `wtp add` from (main worktree\nor any other worktree).\n\n### Symlink Hooks: Shared Assets\n\nSymlink hooks are useful for sharing large or mutable directories from the main\nworktree (e.g. `.bin`, `.cache`, `node_modules`).\n\n- `from`: path is resolved relative to the main worktree (or absolute).\n- `to`: path is resolved relative to the newly created worktree (or absolute).\n\nExample:\n\n```yaml\nhooks:\n  post_create:\n    - type: symlink\n      from: \".bin\"\n      to: \".bin\"\n```\n\n## Shell Integration\n\n### Tab Completion Setup\n\n#### If installed via Homebrew\n\nNo manual setup required. Homebrew installs a tiny bootstrapper that runs\n`wtp shell-init \u003cshell\u003e` the first time you press `TAB` after typing `wtp`. That\nlazy call gives you both tab completion and the `wtp cd` integration for the\nrest of the session—no rc edits needed.\n\nNeed to refresh inside an existing shell? Just run `wtp shell-init \u003cshell\u003e`\nyourself.\n\n#### If installed via go install\n\nAdd a single line to your shell configuration file to enable both completion and\nshell integration:\n\n```bash\n# Bash: Add to ~/.bashrc or ~/.bash_profile\neval \"$(wtp shell-init bash)\"\n\n# Zsh: Add to ~/.zshrc\neval \"$(wtp shell-init zsh)\"\n\n# Fish: Add to ~/.config/fish/config.fish\nwtp shell-init fish | source\n```\n\n\u003e **Note:** Bash completion requires bash-completion v2. On macOS, install\n\u003e Homebrew’s Bash 5.x and `bash-completion@2`, then\n\u003e `source /opt/homebrew/etc/profile.d/bash_completion.sh` (or the path shown\n\u003e after installation) before enabling the one-liner above.\n\nAfter reloading your shell you get the same experience as Homebrew users.\n\n### Navigation with wtp cd\n\nThe `wtp cd` command outputs the absolute path to a worktree. You can use it in\ntwo ways:\n\n#### Direct Usage\n\n```bash\n# Change to a worktree using command substitution\ncd \"$(wtp cd feature/auth)\"\n\n# Change to the main worktree\ncd \"$(wtp cd)\"\n\n# Or explicitly:\ncd \"$(wtp cd @)\"\n```\n\n#### With Shell Hook (Recommended)\n\nFor a more seamless experience, enable the shell hook. `wtp shell-init \u003cshell\u003e`\nalready bundles it, so Homebrew users get the hook automatically and go install\nusers get it from the one-liner above. If you only want the hook without\ncompletions, you can still run `wtp hook \u003cshell\u003e` manually.\n\nThen use the simplified syntax:\n\n```bash\n# Change to a worktree by its name\nwtp cd feature/auth\n\n# Go to the main worktree (same as @)\nwtp cd\n\n# Change to the root worktree using the '@' shorthand\nwtp cd @\n\n# Tab completion works!\nwtp cd \u003cTAB\u003e\n```\n\n#### Complete Setup (Lazy Loading for Homebrew Users)\n\nHomebrew ships a lightweight bootstrapper. Press `TAB` after typing `wtp` and it\nevaluates `wtp shell-init \u003cshell\u003e` once for your session—tab completion and\n`wtp cd` just work.\n\n## Worktree Structure\n\nWith the default configuration (`base_dir: \"../worktrees\"`):\n\n```\n\u003cproject-root\u003e/\n├── .git/\n├── .wtp.yml\n└── src/\n\n../worktrees/\n├── main/\n├── feature/\n│   ├── auth/          # wtp add feature/auth\n│   └── payment/       # wtp add feature/payment\n└── hotfix/\n    └── bug-123/       # wtp add hotfix/bug-123\n```\n\nBranch names with slashes are preserved as directory structure, automatically\norganizing worktrees by type/category.\n\n## Error Handling\n\nwtp provides clear error messages:\n\n```bash\n# Branch not found\nError: branch 'nonexistent' not found in local or remote branches\n\n# Multiple remotes have same branch\nError: branch 'feature' exists in multiple remotes: origin, upstream. Please specify remote explicitly\n\n# Worktree already exists\nError: failed to create worktree: exit status 128\n\n# Uncommitted changes\nError: Cannot remove worktree with uncommitted changes. Use --force to override\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md)\nfor details.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/satococoa/wtp.git\ncd wtp\n\n# Install dependencies\ngo mod download\n\n# Run tests\ngo tool task test\n\n# Build\ngo tool task build\n\n# Run locally\n./wtp --help\n```\n\n### Formatting\n\nRun `go tool task fmt` before sending changes. The formatter uses\n`golangci-lint fmt` (gofmt + goimports) and automatically derives the\n`goimports` `-local` prefix from `go list -m`, so forks and renamed modules\nstay grouped correctly. `go tool golangci-lint fmt ./...` still works for\none-off runs, but the task is the authoritative workflow.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nInspired by git-worktree and the need for better multi-branch development\nworkflows.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatococoa%2Fwtp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatococoa%2Fwtp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatococoa%2Fwtp/lists"}