managing-git

Managing Git Skill

This skill provides patterns and best practices for Git workflows, with trunk-based development as the primary approach.

Primary Workflow: Trunk-Based Development

This plugin emphasizes trunk-based development (TBD) where:

• All work commits directly to main
• Changes are small, atomic, and well-tested
• Feature flags manage incomplete features
• Continuous integration catches issues early

main ────●────●────●────●────●────▶
         │    │    │    │    │
         Small, tested commits

Why Trunk-Based?

1. Faster iteration - No PR review bottleneck for solo/small teams
2. Simpler workflow - One branch, fewer merge conflicts
3. Continuous integration - Issues caught immediately
4. Ship faster - Deploy any commit, use feature flags

Safeguards for Main-Branch Development

• Run tests before every push
• Use /ai-dev:commit-push for quality gates
• Keep commits small and reversible
• Use feature flags for incomplete work
• Always have a revert plan

Alternative: GitHub Flow (For Teams)

When PRs are required (team policy, compliance):

main
  │
  ├── feature/add-auth ──────┐
  │                          │ PR
  ├──────────────────────────┘

Git Flow (Legacy)

For projects requiring release branches (enterprise):

main ────────────────────────────────────────▶
  │                                     ▲
  ├── release/1.0 ──────────────────────┤
develop ──┴─────────────────────────────┴───▶

Conventional Commits

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, no code change
refactor	Neither fix nor feature
perf	Performance improvement
test	Adding tests
chore	Maintenance tasks
ci	CI/CD changes

Examples

feat(auth): add password reset flow

Implement password reset via email with secure tokens.
Tokens expire after 24 hours.

Closes #123

fix(api): handle null response from payment service

The payment service can return null for cancelled transactions.
Added null check and appropriate error handling.

Common Commands

Daily Workflow

# Start work
git checkout main
git pull origin main
git checkout -b feature/my-feature

# During work
git add .
git commit -m "feat: implement feature"

# Sync with main
git fetch origin
git rebase origin/main

# Push
git push -u origin feature/my-feature

Fixing Mistakes

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Amend last commit
git commit --amend -m "new message"

# Undo staged changes
git restore --staged <file>

# Undo working directory changes
git restore <file>

Investigating

# View history
git log --oneline -20

# View changes
git diff HEAD~1
git diff --cached  # staged changes

# Find who changed a line
git blame <file>

# Search commits
git log --grep="keyword"
git log -S "code"  # search for code

Branch Management

# List branches
git branch -a

# Delete branch
git branch -d feature/done
git push origin --delete feature/done

# Rename branch
git branch -m old-name new-name

Merge vs Rebase

Merge

git checkout main
git merge feature/branch

• Preserves complete history
• Creates merge commits
• Better for shared branches

Rebase

git checkout feature/branch
git rebase main

• Creates linear history
• Rewrites commits
• Better for local work

Interactive Rebase

git rebase -i HEAD~3

Commands:

• pick - Keep commit
• reword - Change message
• edit - Pause for amendments
• squash - Combine with previous
• fixup - Combine, discard message
• drop - Remove commit

Cherry-Pick

# Apply specific commit
git cherry-pick abc1234

# Apply without committing
git cherry-pick --no-commit abc1234

Stashing

# Stash changes
git stash
git stash push -m "work in progress"

# List stashes
git stash list

# Apply stash
git stash pop        # apply and remove
git stash apply      # apply and keep

# Drop stash
git stash drop stash@{0}

Tags

# Create tag
git tag v1.0.0
git tag -a v1.0.0 -m "Release 1.0.0"

# Push tags
git push origin v1.0.0
git push origin --tags

# List tags
git tag -l "v1.*"

.gitignore Patterns

# Dependencies
node_modules/
.venv/
__pycache__/

# Build output
dist/
build/
*.egg-info/

# IDE
.idea/
.vscode/
*.swp

# Environment
.env
.env.local
*.local

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Coverage
coverage/
.coverage
htmlcov/

Best Practices

1. Commit often - Small, focused commits
2. Write good messages - Clear and descriptive
3. Pull before push - Stay in sync
4. Use branches - One feature per branch
5. Review before merge - Use pull requests
6. Don't commit secrets - Use .gitignore
7. Tag releases - Semantic versioning
8. Keep main clean - Always deployable