---
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.
