From 1e4a08bd0aadefab0606695929d2f0dc69207e6a Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:36:39 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 ++ README.md | 3 + commands/create_worktree.md | 18 ++ commands/merge_worktree.md | 18 ++ plugin.lock.json | 53 ++++++ skills/git-worktree-patterns/SKILL.md | 246 ++++++++++++++++++++++++++ 6 files changed, 352 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/create_worktree.md create mode 100644 commands/merge_worktree.md create mode 100644 plugin.lock.json create mode 100644 skills/git-worktree-patterns/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..73e2091 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "git-project-management", + "description": "Git worktree management and project planning utilities for efficient version control workflows and parallel development", + "version": "1.1.0", + "author": { + "name": "Claude Code Toolkit" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bbe9659 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# git-project-management + +Git worktree management and project planning utilities for efficient version control workflows and parallel development diff --git a/commands/create_worktree.md b/commands/create_worktree.md new file mode 100644 index 0000000..f5e7575 --- /dev/null +++ b/commands/create_worktree.md @@ -0,0 +1,18 @@ +Create a new Git worktree with branch name and optional path: $ARGUMENTS + +First, parse the arguments to extract: +- Branch name (required, first argument) +- Worktree path (optional, second argument - if not provided, use ../project-{branch-name}) + +Then execute these steps: +1. Verify we're in a Git repository +2. Show current worktrees with `git worktree list` +3. Create the worktree using `git worktree add -b ` +4. Navigate to the new worktree directory +5. List directory contents and check for dependency files (package.json, requirements.txt, etc.) +6. Install dependencies for each service: + - Run `npm ci` in astro/ directory (frontend dependencies) + - Run `npm ci` in strapi/ directory (CMS dependencies) + - Run `npm ci` in tests/ directory (test dependencies) +7. Provide instructions on how to start working in the new worktree +If any errors occur, explain them and suggest solutions. \ No newline at end of file diff --git a/commands/merge_worktree.md b/commands/merge_worktree.md new file mode 100644 index 0000000..345e874 --- /dev/null +++ b/commands/merge_worktree.md @@ -0,0 +1,18 @@ +Merge the current worktree back to the target branch and clean up: $ARGUMENTS + +Parse arguments to extract: +- Target branch (required, first argument like 'master' or 'develop') + +Execute these steps: +1. Check if we're currently in a worktree (not the main repo) +2. Get current branch name with `git branch --show-current` +3. Check for uncommitted changes with `git status` +4. If there are uncommitted changes stop process and ask user to commit changes. +5. Push the current branch to origin +6. Navigate back to the main repository directory +7. Switch to the target branch and pull latest changes +8. Merge the current branch into the target branch +9. Remove the worktree with `git worktree remove ` +10. Ask if I should delete the feature branch locally + +Handle any merge conflicts by explaining the resolution process. \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b5025e9 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:L-Sypniewski/claude-code-toolkit:plugins/git-project-management", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "fa7a89cfeea76ea0c96b0f45cc1814b7f414c51c", + "treeHash": "912328e56598b11d2737b40ca417c0768d9abed691e2dd32c64af93d57020c70", + "generatedAt": "2025-11-28T10:11:59.784399Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "git-project-management", + "description": "Git worktree management and project planning utilities for efficient version control workflows and parallel development", + "version": "1.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "19662d369ecd11ac344da479c38912c8b5548299024cfe5292303a19675fd3f2" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "221c30d582cfafd3f81ec2eb969e934cf92eaeef009553a44093416221080371" + }, + { + "path": "commands/merge_worktree.md", + "sha256": "f6cea4972e4369624615eeb26bd05de356a4404d39afa3c0fc351fb1e85ee0be" + }, + { + "path": "commands/create_worktree.md", + "sha256": "f628a158aa7854598181298daf20718e3618c293db9b6ad32d86a5bc7195860b" + }, + { + "path": "skills/git-worktree-patterns/SKILL.md", + "sha256": "93227d2e9de9cf5c97c118d297166db829870ef2dfd385d9039f3724510d7394" + } + ], + "dirSha256": "912328e56598b11d2737b40ca417c0768d9abed691e2dd32c64af93d57020c70" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/git-worktree-patterns/SKILL.md b/skills/git-worktree-patterns/SKILL.md new file mode 100644 index 0000000..231113e --- /dev/null +++ b/skills/git-worktree-patterns/SKILL.md @@ -0,0 +1,246 @@ +--- +name: git-worktree-patterns +description: Git worktree patterns for parallel development. Use when working on multiple branches simultaneously or when you need to maintain separate working directories for different branches. +--- + +# Git Worktree Patterns + +This skill provides patterns for using Git worktrees to enable parallel development across multiple branches. + +## What are Git Worktrees? + +Git worktrees allow you to have multiple working directories attached to the same repository. Each worktree can be on a different branch, enabling true parallel development without the need to stash or commit incomplete work. + +## Use Cases + +### Parallel Feature Development + +Work on multiple features or branches simultaneously without context switching: + +```bash +# Main working directory +/project (main branch) + +# Additional worktrees +/project-worktrees/feature-a (feature/a branch) +/project-worktrees/feature-b (feature/b branch) +/project-worktrees/hotfix (hotfix/critical branch) +``` + +**Common scenarios**: +- **Urgent hotfix**: Need to fix production issue while working on a feature +- **PR review**: Review someone's PR without stashing your current work +- **Parallel testing**: Run tests on one branch while developing on another +- **Side-by-side comparison**: Compare different implementations or approaches +- **Long-running builds**: Continue working while a build/test runs elsewhere + +## Basic Worktree Commands + +### Creating Worktrees + +```bash +# Create worktree from existing branch +git worktree add ../project-feature-a feature/a + +# Create worktree and new branch +git worktree add -b feature/new-feature ../project-new-feature + +# Create worktree from specific commit +git worktree add ../project-hotfix abc123 + +# Use absolute or relative paths +git worktree add /path/to/worktrees/feature-x feature/x +``` + +### Listing Worktrees + +```bash +# List all worktrees with their branches and paths +git worktree list + +# Example output: +# /project abc123 [main] +# /project-feature-a def456 [feature/a] +# /project-feature-b ghi789 [feature/b] +``` + +### Removing Worktrees + +```bash +# Remove worktree (must not have uncommitted changes) +git worktree remove ../project-feature-a + +# Force remove (discards uncommitted changes) +git worktree remove --force ../project-feature-a + +# Clean up stale worktree references +git worktree prune +``` + +### Moving Between Worktrees + +```bash +# Simply cd to the worktree directory +cd ../project-feature-a + +# All git commands work normally in each worktree +git status +git commit +git push +``` + +## Worktree Organization Patterns + +### Directory Structure + +**Option 1: Sibling directories** +``` +/projects/ + ├─ myproject/ (main) + ├─ myproject-feature-a/ + ├─ myproject-feature-b/ + └─ myproject-hotfix/ +``` + +**Option 2: Nested structure** +``` +/myproject/ (main) + └─ .worktrees/ + ├─ feature-a/ + ├─ feature-b/ + └─ hotfix/ +``` + +**Option 3: Centralized worktrees** +``` +/worktrees/ + ├─ myproject-main/ + ├─ myproject-feature-a/ + ├─ myproject-feature-b/ + └─ other-project-main/ +``` + +### Naming Conventions + +```bash +# Project-branch pattern +git worktree add ../myproject-feature-auth feature/auth + +# Purpose-based pattern +git worktree add ../myproject-review feature/pr-123 + +# Descriptive pattern +git worktree add ../myproject-hotfix-login-bug hotfix/login-bug +``` + +## Advanced Worktree Workflows + +### Hotfix While Developing + +```bash +# You're working in main worktree on feature/large-feature +cd /project + +# Urgent bug reported! +# Create hotfix worktree +git worktree add ../project-hotfix main + +# Switch to hotfix worktree +cd ../project-hotfix + +# Fix the bug +git checkout -b hotfix/critical-bug +# ... make changes ... +git commit -m "fix: critical production bug" +git push + +# Return to feature work without losing context +cd /project +``` + +### PR Review Workflow + +```bash +# You're working on your feature +cd /project + +# Need to review a PR (branch: feature/team-pr) +git fetch origin feature/team-pr +git worktree add ../project-review feature/team-pr + +# Review in separate worktree +cd ../project-review +# ... test, review, run code ... + +# Clean up after review +cd /project +git worktree remove ../project-review +``` + +### Parallel Testing + +```bash +# Run long test suite in one worktree +cd /project-main +npm test # Takes 10 minutes + +# Continue development in another worktree +cd /project-feature-x +# ... keep coding ... +``` + +## Best Practices + +### Do's + +- ✅ Use worktrees for parallel work on different branches +- ✅ Keep worktree directories organized and named clearly +- ✅ Remove worktrees when done to avoid clutter +- ✅ Use `.git/worktrees` to track all worktrees in the main repository +- ✅ Share the same `.git` directory = shared configuration, hooks, and remotes + +### Don'ts + +- ❌ Don't check out the same branch in multiple worktrees (Git prevents this) +- ❌ Don't forget to remove worktrees - they consume disk space +- ❌ Don't create worktrees inside other worktrees +- ❌ Don't manually delete worktree directories (use `git worktree remove`) + +## Troubleshooting + +### Stale Worktree References + +```bash +# If you manually deleted a worktree directory +git worktree prune + +# Force unlock a worktree +git worktree unlock +``` + +### Moving Worktrees + +```bash +# Move worktree to new location +git worktree move + +# Example: +git worktree move ../project-feature-a ../new-location/feature-a +``` + +### Checking Worktree Status + +```bash +# See which branch each worktree is on +git worktree list + +# Check worktree health +git worktree list --porcelain +``` + +## Integration with Plugin Commands + +This skill complements the git-project-management plugin commands: +- `/create_worktree` - Automated worktree creation for parallel development +- `/merge_worktree` - Streamlined worktree merging and cleanup +- Use these commands for guided worktree operations