# Git Workflow

> Git workflow best practices and patterns. Use this skill when working with git operations, creating commits, managing branches, handling pull requests, or establishing team git workflows. Provides guidance on commit messages, branching strategies, and collaboration patterns.

- **Type:** Skill
- **Install:** `agentstack add skill-pfangueiro-claude-code-agents-git-workflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pfangueiro](https://agentstack.voostack.com/s/pfangueiro)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pfangueiro](https://github.com/pfangueiro)
- **Source:** https://github.com/pfangueiro/claude-code-agents/tree/main/.claude/skills/git-workflow

## Install

```sh
agentstack add skill-pfangueiro-claude-code-agents-git-workflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Git Workflow

## Overview

This skill provides comprehensive git workflow best practices, branching strategies, and collaboration patterns. Use it to ensure consistent, professional git usage across your projects.

## When to Use This Skill

- Creating commits with proper messages
- Establishing branching strategies (Git Flow, GitHub Flow, Trunk-Based)
- Handling pull requests and code reviews
- Managing releases and hotfixes
- Resolving merge conflicts
- Setting up git hooks and automation

## Core Workflows

### Commit Message Guidelines

Follow the Conventional Commits specification for clear, semantic commit messages:

**Format:**
```
(): 

```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Formatting, missing semicolons, etc.
- `refactor`: Code restructuring without behavior changes
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `chore`: Build process, dependencies, tooling
- `ci`: CI/CD pipeline changes

**Examples:**
```
feat(auth): add JWT token refresh mechanism

Implement automatic token refresh before expiration.
Tokens are refreshed 5 minutes before expiry.

Closes #123
```

```
fix(api): handle null responses in user service

Add defensive null checks to prevent NPE when
external API returns unexpected null values.

Fixes #456
```

### Branching Strategies

#### Git Flow (Traditional)
Best for: Scheduled releases, multiple version support

**Branches:**
- `main`: Production-ready code
- `develop`: Integration branch for features
- `feature/*`: New features
- `release/*`: Release preparation
- `hotfix/*`: Emergency production fixes

**Workflow:**
```bash
# Start new feature
git checkout develop
git checkout -b feature/user-authentication

# Finish feature
git checkout develop
git merge feature/user-authentication
git branch -d feature/user-authentication

# Create release
git checkout -b release/1.2.0
# Bump version, final testing
git checkout main
git merge release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git checkout develop
git merge release/1.2.0
```

#### GitHub Flow (Simplified)
Best for: Continuous deployment, web applications

**Branches:**
- `main`: Always deployable
- `feature/*`: All changes

**Workflow:**
```bash
# Start work
git checkout -b feature/add-dark-mode

# Make changes, commit often
git commit -m "feat(ui): add dark mode toggle"

# Push and create PR
git push origin feature/add-dark-mode
# Create pull request on GitHub
# After review and CI passes, merge to main
# Deploy from main
```

#### Trunk-Based Development
Best for: High-frequency releases, mature CI/CD

**Key principles:**
- All work on `main` or very short-lived feature branches (>>>>>>
# 3. Resolve manually, keeping appropriate changes
# 4. Remove conflict markers
# 5. Test the resolved code
git add 
git commit -m "chore: resolve merge conflicts with main"
```

**Conflict Resolution Tips:**
- Communicate with the other developer if unsure
- Prefer rebasing for cleaner history (if branch not shared)
- Use `git mergetool` for complex conflicts
- Always test after resolution

### Git Hooks and Automation

Common hooks to consider:

**pre-commit:**
```bash
# Run linters, formatters
npm run lint
npm run format

# Run fast tests
npm run test:unit
```

**commit-msg:**
```bash
# Validate commit message format
# Ensure conventional commits compliance
```

**pre-push:**
```bash
# Run full test suite
npm run test

# Run build
npm run build
```

## Advanced Patterns

### Rebasing vs Merging

**Use Rebase When:**
- Working on personal feature branch
- Want linear history
- Need to incorporate upstream changes

```bash
git fetch origin
git rebase origin/main
```

**Use Merge When:**
- Working on shared branches
- Want to preserve complete history
- Merging pull requests

```bash
git merge origin/main
```

### Cherry-Picking

Use to apply specific commits to another branch:

```bash
# Find commit hash
git log

# Apply to current branch
git cherry-pick 
```

### Interactive Rebase

Clean up commit history before pushing:

```bash
# Rebase last 3 commits
git rebase -i HEAD~3

# Options: pick, reword, squash, fixup, drop
```

## Common Scenarios

### Undo Last Commit (Not Pushed)
```bash
git reset --soft HEAD~1  # Keep changes staged
git reset HEAD~1         # Keep changes unstaged
git reset --hard HEAD~1  # Discard changes
```

### Undo Pushed Commit
```bash
# Create new commit that reverses changes
git revert 
git push origin main
```

### Stash Changes
```bash
# Save work in progress
git stash save "WIP: feature description"

# List stashes
git stash list

# Apply stash
git stash apply stash@{0}

# Apply and remove
git stash pop
```

### Update Commit Message
```bash
# Last commit (not pushed)
git commit --amend -m "new message"

# Older commit
git rebase -i HEAD~n  # Use 'reword'
```

## Worktrees

Git worktrees let you work on multiple branches simultaneously without stashing or switching.

### When to Use Worktrees vs Branches

| Scenario | Use Branch | Use Worktree |
|----------|-----------|-------------|
| Sequential feature work | Yes | No |
| Parallel features (simultaneous) | No | Yes |
| Quick hotfix while mid-feature | Stash + branch | Yes (cleaner) |
| Risky experiment | Maybe | Yes (isolated) |
| Code review while coding | No | Yes |

### Using EnterWorktree/ExitWorktree

Claude Code provides built-in worktree tools:

- **EnterWorktree** — Creates an isolated worktree with a new branch from HEAD. Provide an optional `name` for the worktree.
- **ExitWorktree** — Leave the worktree. Choose `keep` (preserve for later) or `remove` (clean up).

### Common Patterns

**Experiment safely:**
1. `EnterWorktree` with name `experiment-X`
2. Try the risky approach
3. If it works: commit, `ExitWorktree(keep)`, merge later
4. If it fails: `ExitWorktree(remove)` — no mess

**Hotfix while mid-feature:**
1. `EnterWorktree` with name `hotfix-Y`
2. Fix the bug, commit, push
3. `ExitWorktree(remove)` — back to feature work

See the `worktree-workflow` skill for detailed patterns and best practices.

## Resources

### references/
This skill includes reference documentation for deeper dives:

- **git-best-practices.md**: Comprehensive git guidelines
- **branching-models.md**: Detailed branching strategy comparisons
- **conflict-resolution.md**: Advanced merge conflict patterns

## Quick Reference

**Daily Commands:**
```bash
git status                    # Check status
git add                # Stage file
git commit -m "message"      # Commit with message
git push origin      # Push to remote
git pull origin      # Pull from remote
git checkout -b      # Create and switch branch
git merge            # Merge branch
```

**Inspection:**
```bash
git log --oneline --graph    # Visual commit history
git diff                     # See unstaged changes
git diff --staged            # See staged changes
git show             # Show commit details
git blame              # See who changed each line
```

**Cleanup:**
```bash
git branch -d        # Delete local branch
git push origin :    # Delete remote branch
git clean -fd                # Remove untracked files
git gc                       # Garbage collection
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pfangueiro](https://github.com/pfangueiro)
- **Source:** [pfangueiro/claude-code-agents](https://github.com/pfangueiro/claude-code-agents)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-pfangueiro-claude-code-agents-git-workflow
- Seller: https://agentstack.voostack.com/s/pfangueiro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.