--- 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: ``` [optional scope]: [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: ` 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/` | New feature work | | `fix/` | Bug fix | | `hotfix/` | Urgent production patch | | `release/` | Release preparation | | `chore/` | 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 ` | | Discard local changes in file | `git restore ` | | 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 ` | | Fix last commit message | `git commit --amend -m "new message"` | | Add forgotten file to last commit | `git add ; 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 # apply one commit git cherry-pick .. # apply a range git cherry-pick --no-commit # 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 ` 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 # why is a file ignored? git rm --cached # 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:** `` **Branch:** `` **Message:** 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.