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

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.