Agent skill

managing-git

Guides git workflows, branching strategies, commit conventions, and version control best practices. Use when managing repositories, creating branches, or handling merges.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/managing-git-cloudai-x-opencode-workflow

Metadata

Additional technical details for this skill

audience
developers
category
workflow

SKILL.md

Managing Git

Best practices for version control, branching strategies, and collaborative development.

When to Use This Skill

  • Setting up branching strategies
  • Writing commit messages
  • Handling merges and conflicts
  • Managing releases
  • Code review workflows
  • Maintaining clean history

Branching Strategies

Git Flow

main ─────●─────────────────────●─────────────────●────▶
           \                   /                 /
release     \───────●─────────●                 /
              \                                /
develop ───────●───────●───────●──────●───────●────────▶
                \       \       \      \
feature          \───────●───────●      \───●───●
                          \              \
hotfix                     \              \───●────▶ main
Branch Purpose Branches From Merges Into
main Production code - -
develop Integration main release
feature/* New features develop develop
release/* Release prep develop main, develop
hotfix/* Production fixes main main, develop

Use when: Scheduled releases, multiple versions supported

GitHub Flow

main ─────●─────●─────●─────●─────●────▶
           \   /       \   /       \   /
feature     ●─●         ●─●         ●─●
            PR          PR          PR
Branch Purpose
main Always deployable
feature/* All changes (features, fixes)

Use when: Continuous deployment, simple workflow

Trunk-Based Development

main ─────●──●──●──●──●──●──●──●──●──●────▶
           │  │  │  │  │  │  │  │  │  │
          ●   ●  ●  ●  ●  ●  ●  ●  ●  ●
          Small, frequent commits (often direct to main)

Use when: High trust teams, strong CI/CD, frequent deploys

Commit Message Conventions

Conventional Commits

<type>(<scope>): <subject>

<body>

<footer>

Types

Type Description Example
feat New feature feat(auth): add OAuth2 login
fix Bug fix fix(api): handle null response
docs Documentation docs(readme): update setup steps
style Formatting style: fix indentation
refactor Code restructuring refactor(db): simplify query builder
test Adding tests test(user): add registration tests
chore Maintenance chore(deps): update lodash
perf Performance perf(search): add index on email
ci CI/CD changes ci: add Node 18 to matrix

Good vs Bad Commits

BAD:
  - "fix"
  - "update code"
  - "WIP"
  - "changes"
  - "asdfasdf"

GOOD:
  - "fix(auth): prevent session timeout on idle"
  - "feat(cart): add quantity validation"
  - "refactor(api): extract common error handling"

Commit Body Guidelines

fix(payment): prevent double charge on retry

The payment gateway timeout was causing the retry logic to submit
duplicate charges. Added idempotency key to prevent double-processing.

Closes #1234
  • First line: 50 chars max, imperative mood
  • Body: Wrap at 72 chars, explain why, not what
  • Footer: Reference issues, breaking changes

Branch Naming Conventions

Pattern

<type>/<ticket>-<short-description>

Examples

Type Example
Feature feature/AUTH-123-add-oauth-login
Bugfix fix/CART-456-quantity-validation
Hotfix hotfix/PROD-789-memory-leak
Chore chore/update-dependencies
Docs docs/api-documentation

Branch Rules

  1. Lowercase with hyphens
  2. Include ticket number when available
  3. Keep short but descriptive
  4. Delete after merge

Git Workflow Commands

Daily Workflow

bash
# Start new feature
git checkout main
git pull origin main
git checkout -b feature/AUTH-123-add-login

# Work on feature
git add -p                    # Stage hunks interactively
git commit -m "feat(auth): add login form"

# Keep up to date
git fetch origin
git rebase origin/main        # Preferred: clean history
# OR
git merge origin/main         # Alternative: preserves context

# Push and create PR
git push -u origin feature/AUTH-123-add-login

Useful Commands

Command Purpose
git stash Save uncommitted changes temporarily
git stash pop Restore stashed changes
git commit --amend Modify last commit
git rebase -i HEAD~3 Interactive rebase (squash, reorder)
git cherry-pick <sha> Apply specific commit
git bisect Binary search for bug introduction
git reflog View all HEAD movements (recovery)

Cleanup Commands

bash
# Delete merged branches locally
git branch --merged | grep -v main | xargs git branch -d

# Prune remote tracking branches
git fetch --prune

# Clean untracked files (careful!)
git clean -fd

Handling Conflicts

Conflict Resolution Flow

1. Identify conflicts
   git status

2. Open conflicted files
   <<<<<<< HEAD
   your changes
   =======
   their changes
   >>>>>>> feature-branch

3. Resolve (keep one, combine, or rewrite)

4. Mark resolved
   git add <resolved-file>

5. Continue
   git rebase --continue   # if rebasing
   git commit              # if merging

Prevention Strategies

  1. Small, frequent merges - Reduce conflict scope
  2. Communication - Coordinate on shared files
  3. Feature flags - Reduce long-lived branches
  4. Clear ownership - Minimize overlapping work

Pull Request Best Practices

PR Checklist

  • Branch is up to date with main
  • Tests pass locally
  • Linting passes
  • Self-review completed
  • Documentation updated
  • Ticket/issue linked
  • Screenshots for UI changes

PR Size Guidelines

Size Lines Changed Review Time Recommendation
Small 1-100 15 min Ideal
Medium 100-400 30-60 min Acceptable
Large 400+ 1+ hour Split if possible

PR Description Template

markdown
## Summary
Brief description of changes

## Changes
- Added X
- Modified Y
- Removed Z

## Testing
- [ ] Unit tests added
- [ ] Manual testing done

## Screenshots (if applicable)
[Before/After images]

## Related Issues
Closes #123

Release Management

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backward compatible)
  │     └── New features (backward compatible)
  └── Breaking changes

Release Process

bash
# Create release branch
git checkout -b release/v1.2.0 develop

# Bump version, update changelog
# ... make changes ...

# Merge to main and tag
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# Merge back to develop
git checkout develop
git merge release/v1.2.0

Changelog Format

markdown
# Changelog

## [1.2.0] - 2024-01-15
### Added
- OAuth2 authentication support

### Changed
- Improved error messages

### Fixed
- Memory leak in cache handler

### Deprecated
- Old authentication method (use OAuth2)

### Removed
- Legacy API v1 endpoints

Git Hooks

Common Hooks

Hook Timing Use Case
pre-commit Before commit Linting, formatting
commit-msg After message Validate message format
pre-push Before push Run tests
post-merge After merge Install dependencies

Example pre-commit

bash
#!/bin/sh
# .git/hooks/pre-commit

# Run linter
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Please fix errors."
  exit 1
fi

# Run tests
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Please fix before committing."
  exit 1
fi

Using Husky (Node.js)

json
// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Troubleshooting

Common Issues

Problem Solution
Accidental commit to main git reset HEAD~1 (before push)
Wrong branch git stash, switch, git stash pop
Need to undo merge git revert -m 1 <merge-commit>
Lost commits git reflog to find, git cherry-pick
Large file committed git filter-branch or BFG Repo-Cleaner

Recovery Commands

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

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

# Recover deleted branch
git reflog
git checkout -b recovered-branch <sha>

# Undo a pushed commit (safe)
git revert <sha>

Anti-Patterns to Avoid

  1. Force pushing to shared branches - Breaks others' history
  2. Giant commits - Hard to review, hard to bisect
  3. Vague commit messages - "fix" tells nothing
  4. Long-lived branches - Merge conflict hell
  5. Committing generated files - Bloats repo, causes conflicts
  6. Committing secrets - Security risk (even after removal)
  7. Rebasing public history - Breaks collaborators
  8. Ignoring CI failures - Broken windows effect

Quick Reference

BRANCHES:
  main       → Production (protected)
  develop    → Integration (Git Flow)
  feature/*  → New work
  fix/*      → Bug fixes
  hotfix/*   → Production emergencies

COMMITS:
  feat(scope): add feature
  fix(scope): fix bug
  docs(scope): update docs
  refactor(scope): restructure code

DAILY FLOW:
  git checkout -b feature/ticket-desc
  git add -p && git commit
  git rebase origin/main
  git push -u origin feature/ticket-desc

VERSIONING:
  MAJOR.MINOR.PATCH
  Breaking.Feature.Bugfix

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results