327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
---
|
||
name: git
|
||
description: Expert Git workflow assistant. Use this skill whenever the user mentions anything related to Git: writing commit messages, branching, pull requests, merging, rebasing, resolving conflicts, .gitignore files, changelogs, tagging, stashing, cherry-picking, or undoing changes. Also trigger when the user says "commit", "push", "branch", "PR", "merge", "rebase", "diff", or asks "how do I undo" — even if they don't say "Git" explicitly.
|
||
---
|
||
|
||
# Git Workflow Skill
|
||
|
||
Provide expert, context-aware Git guidance. Prefer concise, ready-to-run commands over lengthy explanations. Always tailor advice to the user's apparent workflow (solo dev, team, open-source fork, CI/CD pipeline, etc.).
|
||
|
||
---
|
||
|
||
## 1. Commit Messages
|
||
|
||
Use the **Conventional Commits** format by default unless the user has their own convention:
|
||
|
||
```
|
||
<type>[optional scope]: <short description>
|
||
|
||
[optional body – what and why, not how]
|
||
|
||
[optional footer(s): BREAKING CHANGE, Closes #123, Co-authored-by: …]
|
||
```
|
||
|
||
### Types
|
||
|
||
| Type | When to use |
|
||
| ---------- | -------------------------------------------- |
|
||
| `feat` | New feature (bumps MINOR in SemVer) |
|
||
| `fix` | Bug fix (bumps PATCH) |
|
||
| `docs` | Documentation only |
|
||
| `style` | Formatting, whitespace (no logic change) |
|
||
| `refactor` | Code change that is neither fix nor feat |
|
||
| `perf` | Performance improvement |
|
||
| `test` | Adding or correcting tests |
|
||
| `build` | Build system or dependency changes |
|
||
| `ci` | CI/CD configuration |
|
||
| `chore` | Maintenance tasks, no production code change |
|
||
| `revert` | Reverts a previous commit |
|
||
|
||
Breaking changes: append `!` after the type (`feat!:`) **and/or** add `BREAKING CHANGE: <description>` in the footer.
|
||
|
||
### Workflow for generating a commit message
|
||
|
||
1. Look at the staged diff (`git diff --cached`) or the user's description.
|
||
2. Pick the correct `type` and optional `scope` (module, file area, or feature).
|
||
3. Write the description in the **imperative mood**, lowercase, no trailing period (≤72 chars).
|
||
4. **Always write a body** — even for small changes. The body must be understandable without reading the diff. See domain-specific rules below.
|
||
5. Add footers for issue references (`Closes #42`), breaking changes, or co-authors.
|
||
|
||
### Domain-specific body rules
|
||
|
||
These rules define the **minimum context** a body must contain depending on what was changed.
|
||
|
||
**Skill changes** (files under `.github/skills/`):
|
||
|
||
- Name the skill (e.g. "git skill", "claude-api skill").
|
||
- Name the section or rule that was changed.
|
||
- Explain why it was changed (what problem it solves).
|
||
|
||
**Agent or prompt config changes** (files under `.github/agents/`, `.github/prompts/`):
|
||
|
||
- Name the agent or prompt file.
|
||
- Describe what the file does / what instruction was added or changed.
|
||
- State the motivation.
|
||
|
||
**Migration steps** (files under `Migration/`, `Sources/`, `Tests/`):
|
||
|
||
- State the step number and title (e.g. "Step 3 – Netzwerkschicht").
|
||
- List which files or modules were created or changed.
|
||
- Call out significant decisions explicitly:
|
||
- Libraries or frameworks chosen (and why, if relevant)
|
||
- Architectural patterns introduced (e.g. MVVM, repository pattern, protocol-oriented design)
|
||
- APIs, protocols or data models defined
|
||
- Deviations from the original migration plan
|
||
|
||
**General fallback rule:** the body answers "what was done and why" for a reader who has no access to the diff.
|
||
|
||
**Example – skill change:**
|
||
|
||
```
|
||
chore(git): always write a commit body with domain-specific context
|
||
|
||
git skill, section "Workflow for generating a commit message":
|
||
Added mandatory body rules per change category (skills, agents,
|
||
migration steps) so commit history is readable without the diff.
|
||
Previously the body was optional and often omitted.
|
||
```
|
||
|
||
**Example – migration step:**
|
||
|
||
```
|
||
feat(migration): implement Step 3 – Netzwerkschicht
|
||
|
||
Sources/HVACore/Networking/:
|
||
- APIClient.swift: generic async/await HTTP client using URLSession
|
||
- Endpoint.swift: protocol defining path, method, and body encoding
|
||
- AuthInterceptor.swift: injects Bearer token from KeychainService
|
||
|
||
Decision: chose native URLSession over Alamofire to avoid third-party
|
||
dependency; conforms to the architecture defined in Step 2.
|
||
```
|
||
|
||
**Example – feature with issue reference:**
|
||
|
||
```
|
||
feat(auth): add OAuth2 login via GitHub
|
||
|
||
Users can now sign in with their GitHub account instead of
|
||
creating a separate password. Token is stored in an httpOnly cookie.
|
||
|
||
Closes #88
|
||
```
|
||
|
||
**Example – breaking API change:**
|
||
|
||
```
|
||
feat(api)!: rename /users endpoint to /accounts
|
||
|
||
BREAKING CHANGE: All clients must update their base URL from /users to /accounts.
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Branch Naming
|
||
|
||
| Pattern | Purpose |
|
||
| -------------------------- | ---------------------------- |
|
||
| `main` / `master` | Production-ready code |
|
||
| `develop` | Integration branch (Gitflow) |
|
||
| `feature/<ticket-or-slug>` | New feature work |
|
||
| `fix/<ticket-or-slug>` | Bug fix |
|
||
| `hotfix/<slug>` | Urgent production patch |
|
||
| `release/<version>` | Release preparation |
|
||
| `chore/<slug>` | Maintenance / tooling |
|
||
|
||
Keep branch names lowercase, hyphen-separated, ideally scoped to a ticket ID: `feature/PROJ-42-user-profile`.
|
||
|
||
**Commands:**
|
||
|
||
```bash
|
||
git switch -c feature/PROJ-42-user-profile # create + switch (modern)
|
||
git push -u origin feature/PROJ-42-user-profile
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Pull Request / Merge Request Descriptions
|
||
|
||
A good PR description contains:
|
||
|
||
1. **What** – one-sentence summary of the change.
|
||
2. **Why** – motivation, linked issue.
|
||
3. **How** – relevant implementation decisions (optional for small PRs).
|
||
4. **Testing** – what was tested, test commands.
|
||
5. **Screenshots / recordings** (for UI changes).
|
||
6. **Checklist** – `[ ] Tests pass`, `[ ] Docs updated`, `[ ] No secrets committed`.
|
||
|
||
---
|
||
|
||
## 4. Common Operations – Quick Reference
|
||
|
||
### Undo / Fix
|
||
|
||
| Goal | Command |
|
||
| --------------------------------------- | ---------------------------------------------- |
|
||
| Unstage a file | `git restore --staged <file>` |
|
||
| Discard local changes in file | `git restore <file>` |
|
||
| Undo last commit, keep changes staged | `git reset --soft HEAD~1` |
|
||
| Undo last commit, keep changes unstaged | `git reset HEAD~1` |
|
||
| Undo last commit, **discard** changes | `git reset --hard HEAD~1` ⚠️ |
|
||
| Revert a pushed commit safely | `git revert <sha>` |
|
||
| Fix last commit message | `git commit --amend -m "new message"` |
|
||
| Add forgotten file to last commit | `git add <file>; git commit --amend --no-edit` |
|
||
|
||
> ⚠️ `--hard` and `git push --force` are destructive. Warn the user before suggesting them, especially on shared branches.
|
||
|
||
### Stash
|
||
|
||
```bash
|
||
git stash push -m "WIP: my description" # save
|
||
git stash list # view
|
||
git stash pop # restore latest
|
||
git stash apply stash@{2} # restore specific
|
||
git stash drop stash@{0} # delete
|
||
```
|
||
|
||
### Rebase
|
||
|
||
```bash
|
||
# Update feature branch on top of main
|
||
git switch feature/my-branch
|
||
git fetch origin
|
||
git rebase origin/main
|
||
|
||
# Interactive rebase to clean up last 5 commits
|
||
git rebase -i HEAD~5
|
||
```
|
||
|
||
Interactive rebase actions: `pick`, `reword`, `edit`, `squash` (`s`), `fixup` (`f`), `drop` (`d`).
|
||
|
||
Abort a rebase at any time: `git rebase --abort`.
|
||
|
||
### Cherry-pick
|
||
|
||
```bash
|
||
git cherry-pick <sha> # apply one commit
|
||
git cherry-pick <sha1>..<sha2> # apply a range
|
||
git cherry-pick --no-commit <sha> # stage without committing
|
||
```
|
||
|
||
### Tags / Releases
|
||
|
||
```bash
|
||
git tag -a v1.2.3 -m "Release v1.2.3"
|
||
git push origin v1.2.3
|
||
git push origin --tags # push all tags
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Merge Conflict Resolution
|
||
|
||
1. Run `git status` to see conflicted files.
|
||
2. Open each file — find `<<<<<<< HEAD … ======= … >>>>>>> branch` markers.
|
||
3. Edit to keep the correct code, remove all markers.
|
||
4. `git add <resolved-file>` for each file.
|
||
5. `git commit` (merge) or `git rebase --continue` (rebase).
|
||
|
||
Use a visual tool when helpful:
|
||
|
||
```bash
|
||
git mergetool # uses configured diff tool
|
||
git config --global merge.tool vscode
|
||
```
|
||
|
||
---
|
||
|
||
## 6. .gitignore
|
||
|
||
When asked to create or update a `.gitignore`:
|
||
|
||
1. Identify the language/framework/OS from context.
|
||
2. Use the patterns from [gitignore.io](https://www.toptal.com/developers/gitignore) as a baseline.
|
||
3. Add project-specific entries (secrets files, local config, build artifacts).
|
||
|
||
**Useful commands:**
|
||
|
||
```bash
|
||
git check-ignore -v <file> # why is a file ignored?
|
||
git rm --cached <file> # stop tracking a file already committed
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Changelog Generation
|
||
|
||
When asked to write a CHANGELOG, derive entries from `git log`:
|
||
|
||
```bash
|
||
git log v1.0.0..HEAD --oneline --no-merges
|
||
```
|
||
|
||
Format using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/):
|
||
|
||
```markdown
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
|
||
- …
|
||
|
||
### Changed
|
||
|
||
- …
|
||
|
||
### Fixed
|
||
|
||
- …
|
||
|
||
### Removed
|
||
|
||
- …
|
||
|
||
## [1.2.0] – 2026-04-22
|
||
|
||
### Added
|
||
|
||
- feat(auth): add OAuth2 login via GitHub
|
||
```
|
||
|
||
Group Conventional Commits by type: `feat` → Added, `fix` → Fixed, `refactor/perf` → Changed, `revert` + removals → Removed.
|
||
|
||
---
|
||
|
||
## 8. Safety Rules
|
||
|
||
- Never suggest `git push --force` on `main`/`master`. Use `--force-with-lease` on personal branches.
|
||
- Warn before any `--hard` reset or history-rewriting command.
|
||
- Never include secrets, tokens, or passwords in example commands.
|
||
- When the user is on a team, prefer `git revert` over history rewriting for shared commits.
|
||
|
||
---
|
||
|
||
## 9. After Every Commit
|
||
|
||
After executing a `git commit`, always display the following summary as plain text in the response (no code block, no separate box):
|
||
|
||
**Commit:** `<short-sha>`
|
||
**Branch:** `<branch>`
|
||
**Message:**
|
||
<commit message subject>
|
||
|
||
<commit message body, if present>
|
||
|
||
Example output:
|
||
|
||
**Commit:** `2e4cc9de`
|
||
**Branch:** `master`
|
||
**Message:**
|
||
chore(git): enrich commit messages with mandatory domain-specific context
|
||
|
||
git skill, section 'Workflow for generating a commit message':
|
||
- Step 4 changed from optional to mandatory body
|
||
- Added new section 'Domain-specific body rules'
|
||
|
||
Motivation: commit history should be readable by a user without
|
||
access to the diff or full repository context.
|