# Git Expert

> Advanced Git operations wrapper. Optimizes token usage by guiding complex git workflows into efficient CLI commands.

- Skill: `oimiragieo/git-expert` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add oimiragieo/git-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/git-expert/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/oimiragieo/git-expert

---


# Git Expert Skill

## Installation

The skill invokes the `git` CLI. Install Git if not present:

- **Windows**: Download from [git-scm.com](https://git-scm.com/download/win) or `winget install --id Git.Git -e --source winget`
- **macOS**: `brew install git` or Xcode CLI tools: `xcode-select --install`
- **Linux**: `apt-get install git` (Debian/Ubuntu), `dnf install git` (Fedora), `pacman -S git` (Arch)

Verify: `git --version`

## Cheat Sheet & Best Practices

**Essential commands (token-efficient):**

- `git status -s` — short status; `git add -p` — stage hunks; `git diff --cached` — review staged
- `git switch -c <branch>` or `git checkout -b <branch>` — new branch; `git branch` — list
- `git log --oneline -5` — compact history; `git log --follow <file>` — track renames
- `git restore <file>` — discard unstaged; `git reset --soft HEAD~1` — undo last commit (keep changes)
- `git fetch` then `git merge` or `git pull` — prefer fetch+merge over blind pull

**Hacks:** Set `git config --global color.ui auto` and `user.name`/`user.email`. Use `.gitignore` aggressively. Prefer `git merge --squash` for clean history on feature merge. Use `git cherry-pick <commit>` to bring single commits. Never rebase pushed commits without team agreement.

## Certifications & Training

**Free / official:** [Atlassian Git Tutorials](https://www.atlassian.com/git/tutorials) (beginner–advanced). [Microsoft Learn – GitHub Training](https://learn.microsoft.com/en-us/training/github/) (GitHub Foundations path). [GitHub Learn](https://skills.github.com/) (Git + GitHub). No single “Git cert”; GitHub Foundations aligns with fundamentals.

**Skill data:** Focus on branching, undo (reset/restore/revert), merge vs rebase, remote workflow, and safety (no force-push, no secrets).

## Hooks & Workflows

**Suggested hooks:** Pre-commit: run `commit-validator` (conventional commits). Pre-push: run tests (reference `tdd` / `verification-before-completion`). Post-merge: optional memory/learnings update.

**Workflows:** Use with **developer** (primary), **devops** (always). Flow: branch → edit → add → validate commit message → commit → push; use **github-ops** or **github-mcp** for PR/create. See `.claude/workflows` for feature-development and code-review workflows that use git-expert.

## ⚡ Token-Efficient Workflow

Do not use `git status` repeatedly. Use this workflow:

1. **Check State**: `git status -s` (Short format saves tokens)
2. **Diff**: `git diff --cached` (Only check what you are about to commit)
3. **Log**: `git log --oneline -5` (Context without the noise)

## 🔄 Common Patterns

### Safe Commit

```bash
git add <file>
git diff --cached # REVIEW THIS!
git commit -m "feat: description"
```

### Undo Last Commit (Soft)

```bash
git reset --soft HEAD~1
```

### Fix Merge Conflict

1. `git status` to see conflict files.
2. Edit file to resolve markers (`<<<<`, `====`, `>>>>`).
3. `git add <file>`
4. `git commit --no-edit`

## Iron Laws

1. **NEVER** use `git push --force` on shared branches — force-pushing rewrites history for all collaborators, causes lost commits, and breaks in-progress rebases silently; use `--force-with-lease` when truly necessary.
2. **NEVER** commit secrets, credentials, or tokens to the repository — once pushed, secrets are visible in all forks and clones forever even after deletion from HEAD.
3. **ALWAYS** run the test suite and verify it passes before pushing to shared branches — broken code in shared branches blocks everyone and triggers emergency rollbacks.
4. **ALWAYS** rebase feature branches onto the base branch before merging — merging with a stale base creates avoidable conflicts and produces noisy merge commits in shared history.
5. **NEVER** rebase or rewrite history on commits that have already been pushed to a shared remote — teammates' local branches will diverge and produce duplicate commits on next pull.

## Anti-Patterns

| Anti-Pattern                            | Why It Fails                                                              | Correct Approach                                                           |
| --------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `git push --force` on shared branches   | Overwrites teammates' commits; destroys in-progress rebase branches       | Use `--force-with-lease` for personal branches only; never on main/develop |
| Committing `.env` or credentials        | Permanently visible in history even after deletion; requires key rotation | Add sensitive files to `.gitignore`; use pre-commit secret-scanning hooks  |
| Long-lived feature branches (>5 days)   | Massive merge conflicts; integration bugs discovered too late             | Use short-lived branches with daily rebases onto main (trunk-based dev)    |
| `git commit -m "fix"` or `wip` messages | Makes `git log` useless for bisect and changelog generation               | Use conventional commits: `fix: resolve null pointer in user auth`         |
| Merging without pulling latest base     | Stale merge base; CI catches conflicts only after the merge lands         | `git fetch && git rebase origin/main` before any merge or PR               |

## Git 2.45–2.50 Features (2024–2025)

### Reftable Backend (Git 2.45+)

The reftable backend completely replaces the legacy `files` reference format with a binary format that is faster, atomic, and storage-efficient:

**Benefits:**

- Atomic multi-ref updates (all-or-nothing transactions)
- Faster single-ref lookup and iteration over ref ranges
- Consistent reads — never reads a partial update state
- More efficient reflog storage

**Enable for a new repository:**

```bash
git init --ref-format=reftable my-repo
```

**Check current backend:**

```bash
git rev-parse --show-ref-format
# outputs: files  OR  reftable
```

**Migration note:** Converting an existing repo from `files` to `reftable` requires re-cloning or using `git clone --ref-format=reftable`. Clients using `files` repos are unaffected — the backend is server/local only.

### Incremental Multi-Pack Indexes (Git 2.47+)

Multi-pack indexes (MIDXs) allow Git to maintain a single index across multiple packfiles without repacking. Git 2.47 adds incremental MIDX updates — only newly added packs are indexed rather than rebuilding the full MIDX:

```bash
# Generate or update multi-pack index
git multi-pack-index write --stdin-packs

# Verify the MIDX
git multi-pack-index verify

# Enable via maintenance
git maintenance start
```

**Multi-pack reachability bitmaps** extend MIDX with precomputed reachability data, dramatically speeding up `git clone`, `git fetch`, and garbage collection on large repositories.

### Sparse Checkout for Monorepos (Git 2.25+ cone mode)

Sparse checkout lets you check out only the directories you need from a large monorepo:

```bash
# Clone without checking out any files
git clone --no-checkout --filter=blob:none https://github.com/org/monorepo.git
cd monorepo

# Initialize in cone mode (recommended — uses fast prefix matching)
git sparse-checkout init --cone

# Check out only specific directories
git sparse-checkout set frontend docs shared/utils

# See what is currently checked out
git sparse-checkout list

# Add more directories without losing current ones
git sparse-checkout add backend/api

# Disable sparse checkout (restore full working tree)
git sparse-checkout disable
```

**One-command clone (Git 2.25+):**

```bash
git clone --filter=blob:none --sparse https://github.com/org/monorepo.git
cd monorepo
git sparse-checkout set services/payments
```

**Cone mode vs. non-cone mode:**

| Mode               | Pattern Matching              | Performance                   |
| ------------------ | ----------------------------- | ----------------------------- |
| Cone (recommended) | Directory prefix only         | Fast (O(log n) path matching) |
| Non-cone           | Full gitignore-style patterns | Slow on large trees           |

### Git Scalar — Large Repository Optimization

Scalar is a repository management tool bundled with Git (since Git 2.38) that configures and maintains all recommended performance settings automatically:

```bash
# Clone a large repo with all performance features enabled
scalar clone https://github.com/org/large-monorepo.git

# Register an existing repo with Scalar
scalar register

# Run all maintenance tasks manually
scalar run all

# View configured enlistments
scalar list
```

**What Scalar configures automatically:**

- Partial clone (`--filter=blob:none`)
- Sparse checkout (cone mode)
- File system monitor (`core.fsmonitor`)
- Commit graph generation
- Background maintenance (hourly fetch, daily gc)
- Multi-pack index

### Sign Commits with SSH Keys (Git 2.34+)

SSH key signing is simpler than GPG and works with keys you already use for authentication:

```bash
# Configure SSH signing globally
git config --global gpg.format ssh
git config --global user.signingKey ~/.ssh/id_ed25519.pub

# Sign all commits automatically
git config --global commit.gpgSign true

# Or sign a single commit manually
git commit -S -m "feat: add payment service"

# Verify a commit
git verify-commit HEAD
```

**Set up an allowed-signers file for team verification:**

```bash
# ~/.config/git/allowed_signers
alice@example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
bob@example.com   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
```

```bash
git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
git log --show-signature
```

**GitHub verification:** Add your SSH signing key to GitHub under `Settings > SSH and GPG keys > New SSH key > Signing Key`. Commits signed with that key will show "Verified" on GitHub.

**FIDO2 / hardware security key signing:**

```bash
# Generate a resident key on a FIDO2 security key (e.g., YubiKey)
ssh-keygen -t ed25519-sk -O resident -f ~/.ssh/id_ed25519_sk_fido2
git config --global user.signingKey ~/.ssh/id_ed25519_sk_fido2.pub
```

### Improved Merge Strategies (Git 2.38+ `ort`)

The `ort` merge strategy has been the default since Git 2.34. It is significantly faster than `recursive` for large trees and more deterministic:

```bash
# ort is the default; explicitly select if needed
git merge -s ort feature/my-feature

# Rename detection threshold (default 50%)
git merge -X rename-threshold=80 feature/rename-heavy-branch

# Conflict style: diff3 (shows common ancestor) — strongly recommended
git config --global merge.conflictStyle diff3
# Or zdiff3 (even cleaner context in conflicts, Git 2.35+)
git config --global merge.conflictStyle zdiff3
```

### Performance Commands for Large Repos

```bash
# Enable file system monitor (avoids scanning entire tree for status)
git config core.fsmonitor true
git config core.untrackedCache true

# Precompute commit graph for faster log/blame
git commit-graph write --reachable --changed-paths
git config fetch.writeCommitGraph true

# Partial clone — skip large blobs on clone, fetch on demand
git clone --filter=blob:none <url>

# Shallow clone (CI use case — last N commits only)
git clone --depth=1 <url>

# Check repository health and performance
GIT_TRACE_PERFORMANCE=1 git status
```

## Related Skills

- [`gitflow`](../gitflow/SKILL.md) - Branch workflow patterns (feature, release, hotfix branches)

## Memory Protocol (MANDATORY)

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**

- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.