home / skills / eyadsibai / ltk / git-workflows

git-workflows skill

safe

/plugins/ltk-github/skills/git-workflows

This skill guides your git workflows from commit messages to PRs and branching, improving consistency and traceability across projects.

npx playbooks add skill eyadsibai/ltk --skill git-workflows

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.2 KB

---
name: Git Workflows
description: This skill should be used when the user asks to "create a commit", "write commit message", "create a pull request", "generate changelog", "manage branches", "git workflow", "merge strategy", "PR description", or mentions git operations and version control workflows.
version: 1.0.0
---

# Git Workflows

Comprehensive git workflow skill for commits, pull requests, branching, and changelog generation.

---

## Commit Message Format

### Conventional Commits

| Part | Purpose | Example |
|------|---------|---------|
| **Type** | Category of change | `feat`, `fix`, `docs` |
| **Scope** | Affected component | `(auth)`, `(api)` |
| **Subject** | Brief description | `add OAuth2 login` |
| **Body** | Details (optional) | Why + what changed |
| **Footer** | References | `Closes #123` |

### Commit Types

| Type | When to Use |
|------|-------------|
| **feat** | New feature |
| **fix** | Bug fix |
| **docs** | Documentation only |
| **style** | Formatting (no code change) |
| **refactor** | Code restructuring |
| **test** | Adding/updating tests |
| **chore** | Maintenance, deps |
| **perf** | Performance improvement |

### Commit Analysis Workflow

1. Run `git diff --staged` to see changes
2. Identify change type (feat, fix, etc.)
3. Determine scope (affected component)
4. Write concise subject (< 50 chars)
5. Add body if context needed

---

## Pull Request Structure

### PR Template Elements

| Section | Content |
|---------|---------|
| **Summary** | What this PR does (1-2 sentences) |
| **Changes** | Bullet list of specific changes |
| **Testing** | How changes were tested |
| **Screenshots** | If UI changes |
| **Checklist** | Tests pass, docs updated |

### PR Analysis Workflow

1. List commits: `git log main..HEAD --oneline`
2. Identify themes across commits
3. Note any breaking changes
4. Check test coverage
5. Review documentation needs

---

## Branch Strategies

### Git Flow

| Branch | Purpose |
|--------|---------|
| **main** | Production code |
| **develop** | Integration branch |
| **feature/** | New features |
| **release/** | Release preparation |
| **hotfix/** | Production fixes |

### GitHub Flow

| Branch | Purpose |
|--------|---------|
| **main** | Always deployable |
| **feature branches** | Short-lived work |

### Trunk-Based

| Branch | Purpose |
|--------|---------|
| **main** | All development |
| **Short branches** | < 1 day |
| **Feature flags** | Incomplete work |

### Branch Naming

| Pattern | Example |
|---------|---------|
| Feature | `feature/ABC-123-add-user-auth` |
| Bugfix | `bugfix/ABC-456-fix-login` |
| Hotfix | `hotfix/critical-security-patch` |
| Release | `release/v1.2.0` |

---

## Changelog Format

### Keep a Changelog Structure

| Section | Content |
|---------|---------|
| **Added** | New features |
| **Changed** | Changes in existing functionality |
| **Deprecated** | Soon-to-be removed features |
| **Removed** | Removed features |
| **Fixed** | Bug fixes |
| **Security** | Security fixes |

### Changelog Generation Workflow

1. Get commits since last release tag
2. Parse commit messages for type/scope
3. Group by category (Added, Fixed, etc.)
4. Format with links to issues/PRs

---

## Best Practices

### Commits

| Practice | Why |
|----------|-----|
| Atomic commits | One logical change per commit |
| Clear messages | Explain why, not just what |
| Reference issues | Link to related tickets |
| Sign commits | GPG verification |

### Pull Requests

| Practice | Why |
|----------|-----|
| Small PRs | < 400 lines ideal for review |
| Clear title | Summarize the change |
| Self-review first | Check diff before requesting |
| Respond promptly | Address feedback quickly |

### Branches

| Practice | Why |
|----------|-----|
| Short-lived | Merge within days |
| Up to date | Rebase regularly |
| Clean history | Squash before merge |
| Delete after merge | Keep repo clean |

---

## Merge Strategies

| Strategy | When to Use | Result |
|----------|-------------|--------|
| **Merge commit** | Preserve history | Merge commit node |
| **Squash** | Clean up messy history | Single commit |
| **Rebase** | Linear history | No merge commit |
| **Fast-forward** | Simple, linear | No merge commit |

**Key concept**: Squash for feature branches with messy commits. Rebase for clean linear history. Merge commit when branch history matters.

---

## Common Git Commands

### Pre-Commit

| Command | Purpose |
|---------|---------|
| `git status` | See staged/unstaged changes |
| `git diff --staged` | Review what will be committed |
| `git add -p` | Interactive staging |

### Commit

| Command | Purpose |
|---------|---------|
| `git commit -m "msg"` | Commit with message |
| `git commit --amend` | Fix last commit (before push) |

### Branch Management

| Command | Purpose |
|---------|---------|
| `git branch -d name` | Delete merged branch |
| `git fetch --prune` | Remove stale remotes |
| `git rebase main` | Update branch with main |

### PR Workflow

| Command | Purpose |
|---------|---------|
| `git push -u origin branch` | Push and set upstream |
| `gh pr create` | Create PR via CLI |
| `gh pr merge` | Merge PR via CLI |

## Resources

- Conventional Commits: <https://www.conventionalcommits.org/>
- Keep a Changelog: <https://keepachangelog.com/>
- Git Book: <https://git-scm.com/book>

Overview

This skill provides practical guidance and templates for commits, pull requests, branch strategies, merge strategies, and changelog generation. It helps you produce consistent commit messages, create focused PRs, manage branches effectively, and generate clear changelogs. Use it to standardize workflows across teams and speed review and release processes.

How this skill works

The skill inspects staged and recent commits, suggests Conventional Commit-compliant messages, and recommends a PR structure based on commit themes and testing notes. It maps changes to changelog categories by parsing commit types and scopes, and advises on branch naming and merge strategy best suited to your workflow. It also lists concrete git commands to perform each step.

When to use it

When creating a new commit or drafting a commit message
When opening or writing a pull request description
When planning branch names and branch lifecycle strategies
When deciding whether to squash, rebase, or merge
When generating release notes or a changelog

Best practices

Write atomic commits that capture one logical change
Follow Conventional Commits: type(scope): subject, with body and footer as needed
Keep PRs small, include testing steps, and self-review before request
Use clear branch names: feature/, bugfix/, hotfix/, release/ with ticket IDs
Choose merge strategy deliberately: squash for cleanup, rebase for linear history, merge commits when history matters

Example use cases

Draft a concise Conventional Commit message for staged changes
Generate a PR description listing summary, changes, testing, and checklist
Name and create a feature branch following team convention
Generate a changelog section from commits since the last tag grouped by Added/Changed/Fixed
Recommend a merge strategy for a feature branch with messy intermediate commits

FAQ

How should I format a commit message?

Use Conventional Commits: type(scope): subject (under 50 chars). Add a body explaining why and a footer for issue references, e.g. Closes #123.

When should I squash vs rebase vs merge?

Squash to condense a feature branch into one commit; rebase to keep a linear history and update with main; use merge commits when preserving branch history or multiple contributors matters.