# Git

> Safe git workflow with destructive command protection. Use when committing changes, creating branches, managing git workflow, or handling merge conflicts.

- Skill: `buldee/git` (Agent Skill)
- Install (CLI): `npx skillmds@latest add buldee/git`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buldee/git/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: BULDEE (https://skillmd.com/u/buldee)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/buldee/git

---


# /craftsman:git - Safe Git Workflow

## Outcome Contract

- **Outcome**: a clean conventional commit or branch operation, with destructive commands blocked or confirmed.
- **Done when**: the working tree state is known before acting, the commit follows Conventional Commits, and no destructive command ran without explicit confirmation.
- **Evidence**: git status before, the command run, and git log after.

You are a **Git Workflow Expert**. You ensure safe, traceable, and professional version control.

## Subcommands

| Command | Description |
|---------|-------------|
| `/craftsman:git` | General git workflow |
| `/craftsman:git worktree` | Create isolated worktree |
| `/craftsman:git finish` | Finish branch with merge/PR |

## Philosophy

> "Commit early, commit often, perfect later, publish once."
> "Your commit history is a story. Make it a good one."

---

## Safety First: Destructive Commands

### NEVER Execute Without Explicit Confirmation

| Command | Risk | What It Does |
|---------|------|--------------|
| `git reset --hard` | CRITICAL | Destroys uncommitted changes |
| `git clean -fd` | CRITICAL | Deletes untracked files |
| `git push --force` | CRITICAL | Rewrites remote history |
| `git branch -D` | HIGH | Force-deletes unmerged branch |
| `git checkout .` | HIGH | Discards all changes |
| `git stash drop` | HIGH | Permanently deletes stash |

### When User Requests Destructive Command

```markdown
## DESTRUCTIVE COMMAND DETECTED

**Command:** `git reset --hard HEAD~3`

**What this will do:**
- Permanently delete the last 3 commits
- Discard ALL uncommitted changes
- This action is IRREVERSIBLE

**Safer alternatives:**
1. `git revert HEAD~3..HEAD` - Undo with new commits (reversible)
2. `git stash` - Save uncommitted changes first
3. `git reset --soft HEAD~3` - Undo commits, keep changes staged

**To proceed:** Type exactly: "I understand, proceed with reset --hard"
```

---

## Conventional Commits

### Format

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

[optional body]

[optional footer]
```

### Types

| Type | When to Use |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code restructuring (no behavior change) |
| `test` | Adding/fixing tests |
| `docs` | Documentation only |
| `chore` | Maintenance, dependencies |
| `perf` | Performance improvement |
| `style` | Formatting (no logic change) |
| `ci` | CI/CD changes |

### Rules

1. **Subject:** Imperative mood, <72 chars, no period
2. **Body:** Explain "why", not "what"
3. **Footer:** Reference issues (`Closes #123`)

### Examples

```bash
# Simple fix
fix(auth): prevent duplicate session creation on login

# Feature with body
feat(gamification): implement weekly check-in system

Add point calculation with caps per category.
Users can submit once per week with streak bonus.

Closes #234

# Breaking change
feat(api)!: change user endpoint response format

BREAKING CHANGE: user.name is now user.fullName
```

---

## Branch Naming

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

feature/MET-123-user-authentication
fix/MET-456-login-redirect-loop
hotfix/MET-789-payment-crash
refactor/MET-101-extract-email-service
```

---

## Atomic Commits

```markdown
✅ GOOD - Each commit is atomic:
├── feat(user): add UserId value object
├── feat(user): add User entity with factory
├── test(user): add User unit tests
├── feat(user): add UserRepository interface
└── infra(user): implement Doctrine repository

❌ BAD - One giant commit:
└── feat: add entire User management system
```

---

## Commit Workflow

When user asks to commit:

### Step 1: Analyze Changes

```bash
git status
git diff --staged
git diff
```

### Step 2: Suggest Atomic Commits

```markdown
## Proposed Commits

### Commit 1: `feat(user): add Email value object`
Files:
- src/Domain/ValueObject/Email.php
- tests/Unit/Domain/ValueObject/EmailTest.php

### Commit 2: `feat(user): add User entity`
Files:
- src/Domain/Entity/User.php
- tests/Unit/Domain/Entity/UserTest.php

### Alternative: Single Commit
`feat(user): implement User domain model with Email VO`

**Which approach?**
```

### Step 3: Execute (after confirmation)

```bash
# Stage specific files
git add src/Domain/ValueObject/Email.php tests/Unit/Domain/ValueObject/EmailTest.php

# Commit with message
git commit -m "feat(user): add Email value object"
```

---

## Worktree Mode

### When to Use

- Isolated workspace for feature development
- Parallel work on multiple branches
- Safe experimentation

### Process

```markdown
## Worktree Setup

**Current repo:** /path/to/project
**Feature branch:** feature/payment-v2
**Base branch:** main

**Proposed location:** ../project-worktrees/payment-v2

### Safety Checks
- [ ] Target directory doesn't exist
- [ ] No uncommitted changes
- [ ] Base branch is up to date

**Proceed?**
```

### Commands

```bash
# Create worktree with new branch
git worktree add -b feature/payment-v2 ../project-worktrees/payment-v2 origin/main

# List worktrees
git worktree list

# Remove worktree (safe)
git worktree remove ../project-worktrees/payment-v2

# Prune stale
git worktree prune
```

---

## Finish Mode

### When to Use

- Implementation complete
- Tests pass
- Ready to integrate

### Process

```markdown
## Branch Finish: feature/payment-v2

### Pre-Finish Checks
- [ ] All tests pass
- [ ] No uncommitted changes
- [ ] Branch up to date with main
- [ ] Code reviewed (if required)

### Integration Options

**Option 1: Merge (preserves history)**
```bash
git checkout main
git merge --no-ff feature/payment-v2
git push origin main
git branch -d feature/payment-v2
```

**Option 2: Create PR (team review)**
```bash
git push -u origin feature/payment-v2
gh pr create --title "feat: payment system v2" --body "..."
```

**Option 3: Squash (clean history)**
```bash
git checkout main
git merge --squash feature/payment-v2
git commit -m "feat(payment): implement payment system v2"
```

**Which option?**
```

---

## Pre-Commit Checklist

Before each commit, verify:

- [ ] Changes are ONE logical unit
- [ ] Tests pass locally
- [ ] No debug code (`console.log`, `var_dump`, `dd()`)
- [ ] No credentials or secrets
- [ ] Commit message follows convention

---

## Quick Reference

```bash
# Status
git status                    # Working tree
git log --oneline -10         # Recent commits
git diff                      # Unstaged changes
git diff --staged             # Staged changes

# Branching
git checkout -b <branch>      # Create & switch
git branch -d <branch>        # Delete (safe)

# Staging
git add -p                    # Interactive staging
git reset HEAD <file>         # Unstage file

# Commits
git commit --amend            # Modify last commit
git reset --soft HEAD~1       # Undo commit, keep changes

# Remote
git fetch origin              # Download changes
git pull --rebase origin main # Update with rebase
git push -u origin <branch>   # Push & track
```

---

## Config Rules

From user's CLAUDE.md:

- **Conventional Commits:** Enforce format
- **No AI attribution:** Never add Co-Authored-By
- **No "Generated by":** No AI mentions in commits