# Git Workflow

> Follow correct git workflow for business-automation repo including branch naming, commit message format, and PR conventions. Use when making code changes, creating branches, or preparing commits.

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

---


# Git Workflow Skill

This skill teaches you the correct git workflow conventions for the business-automation repository.

## Branch Naming Convention

**Pattern**: `NNN-feature-name`

- `NNN`: 3-digit zero-padded number (001, 002, etc.)
- `feature-name`: lowercase, hyphen-separated description

**Examples**:
- `001-tui-error-handling`
- `002-reliable-email-detection`
- `006-opencode-skills`

**To find the next number**:
```bash
git branch -a | grep -oE '^[0-9]{3}' | sort -n | tail -1
# Then increment by 1
```

## Commit Message Format

**Pattern**: `[subfolder] description`

- `[subfolder]`: The folder where most changes occurred
- `description`: Brief, lowercase description of changes

**Examples**:
- `[recruitment-automation] fix email detection logic`
- `[.opencode] add shakudo-microservice skill`
- `[specs] create 006-opencode-skills specification`

**Rules**:
- Start with lowercase (except for the bracketed prefix)
- Use present tense ("add", "fix", "update", not "added", "fixed")
- Keep under 72 characters
- Be specific about what changed

## Standard Workflow

### Creating a New Branch

```bash
# 1. Ensure you're on main and up-to-date
git checkout main
git pull origin main

# 2. Create and switch to new branch
git checkout -b NNN-feature-name

# 3. Make your changes
# ...

# 4. Stage changes
git add .

# 5. Commit with proper format
git commit -m "[subfolder] description"

# 6. Push to origin
git push -u origin NNN-feature-name
```

### Updating an Existing Branch

```bash
# 1. Ensure you have latest main
git checkout main
git pull origin main

# 2. Switch back to your branch
git checkout NNN-feature-name

# 3. Rebase onto main (preferred) or merge
git rebase main
# OR
git merge main

# 4. Push updates (use --force-with-lease after rebase)
git push --force-with-lease origin NNN-feature-name
```

### Before Creating a PR

1. **Pull latest main** to avoid conflicts:
   ```bash
   git checkout main && git pull origin main
   git checkout NNN-feature-name && git rebase main
   ```

2. **Run tests** if applicable:
   ```bash
   npm test && npm run lint
   ```

3. **Push final changes**:
   ```bash
   git push origin NNN-feature-name
   ```

## Commit Best Practices

### DO:
- Make atomic commits (one logical change per commit)
- Write descriptive commit messages
- Include the subfolder prefix
- Commit frequently during development

### DON'T:
- Commit sensitive data (.env files, credentials)
- Use `git commit --amend` after pushing (unless you know what you're doing)
- Force push to shared branches without coordination
- Commit generated files (node_modules, dist, __pycache__)

## Common Git Operations

### Check Status
```bash
git status
```

### View Changes
```bash
# Unstaged changes
git diff

# Staged changes
git diff --staged

# Compare with main
git diff main...HEAD
```

### Stage Specific Files
```bash
git add path/to/file.ts
git add folder/
```

### Unstage Files
```bash
git reset HEAD path/to/file.ts
```

### Discard Local Changes
```bash
# Single file
git checkout -- path/to/file.ts

# All changes (CAREFUL!)
git checkout -- .
```

### View Commit History
```bash
# Recent commits
git log --oneline -10

# With graph
git log --oneline --graph --all
```

### Stash Changes
```bash
# Save current changes
git stash

# Restore changes
git stash pop

# List stashes
git stash list
```

## Working with Specs (Speckit Integration)

When working on features with Speckit:

1. **Spec location**: `specs/NNN-feature-name/`
2. **Branch should match spec**: Branch `006-opencode-skills` -> Spec `specs/006-opencode-skills/`
3. **Commit specs separately**: 
   ```bash
   git add specs/006-opencode-skills/
   git commit -m "[specs] create 006-opencode-skills specification"
   ```

## Gitignore Patterns

Ensure these are ignored (check `.gitignore`):

```gitignore
# Dependencies
node_modules/
.venv/

# Build outputs
dist/
build/
*.pyc
__pycache__/

# Environment
.env
.env.local
*.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db
```

## Troubleshooting

### Merge Conflicts

1. Open conflicted files
2. Look for conflict markers: `<<<<<<<`, `=======`, `>>>>>>>`
3. Edit to resolve, keeping desired code
4. Stage resolved files: `git add <file>`
5. Continue: `git rebase --continue` or `git merge --continue`

### Undo Last Commit (Not Pushed)

```bash
# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset HEAD~1

# Discard changes completely (CAREFUL!)
git reset --hard HEAD~1
```

### Fix Commit Message

```bash
# Only if not pushed!
git commit --amend -m "[subfolder] corrected message"
```

### Recover Deleted Branch

```bash
# Find the commit hash
git reflog

# Recreate branch
git checkout -b branch-name <commit-hash>
```