home / skills / trevors / dot-claude / git-workflow

git-workflow skill

safe

/skills/git-workflow

This skill helps you squash commits and safely rebase feature branches to keep history clean and collaboration smooth.

npx playbooks add skill trevors/dot-claude --skill git-workflow

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

Files (2)

SKILL.md

1.6 KB

---
name: git-workflow
description: Handle squashing multiple commits and rebasing feature branches safely. Use when consolidating commits into a single commit, or rebasing feature branches onto updated development branches. Falls back from jj when not available.
---

# Git Workflow

Safe, non-interactive approaches for squashing commits and rebasing feature branches.

> **Tip**: If jj is available (`jj root` succeeds), prefer jj-workflow—it's simpler and has automatic safety via oplog.

## Squash N Commits

```bash
git reset --soft HEAD~3
git commit -m "Your consolidated message"
```

That's it. The `--soft` flag keeps your changes staged and ready to commit.

## Rebase Feature Branch

Update dev first, then rebase:

```bash
git fetch origin dev && git checkout dev && git pull
git checkout my-feature
git rebase --committer-date-is-author-date dev
git push -f origin my-feature
```

The `--committer-date-is-author-date` flag puts your feature commits on top chronologically.

## Key Safety Rules

- **Never rebase shared branches** — only rebase local feature branches
- **Check `git status` first** — ensure no uncommitted changes
- **Create a backup branch**: `git branch backup-$(date +%s)`
- **Review changes** before committing: `git diff --cached`

## Pre-Commit Hook Changes

If hooks modify files during commit, stage and amend:

```bash
git add .
git commit --amend --no-edit
```

## When Things Go Wrong

```bash
git rebase --abort              # Stop rebase, go back
git reflog                      # See recent commits
git reset --hard <commit-hash>  # Recovery
```

See REFERENCE.md for detailed workflows and troubleshooting.

Overview

This skill provides safe, non-interactive Git workflows for squashing multiple commits and rebasing feature branches. It favors simplicity and predictable recovery steps, and falls back from using jj when jj is not available. The patterns are practical for consolidating history and keeping feature branches current with a development branch.

How this skill works

The skill exposes simple commands: a soft reset plus a single commit to squash N commits, and a controlled rebase sequence to replay a feature branch on top of an updated dev branch. It includes pre-checks and recovery commands so you can abort or recover from mistakes. When jj is present, prefer the jj workflow for automatic oplog safety; otherwise the provided Git commands are safe for local feature branches.

When to use it

You want to consolidate several local commits into a single, cleaner commit before merging.
You need to rebase a local feature branch onto an updated dev branch to test integration or resolve conflicts early.
When you want a non-interactive, scriptable approach for CI or team cleanup tasks.
When jj is not installed or available and you need a pure Git fallback.

Best practices

Never rebase branches that are shared with others; only rebase local feature branches.
Run git status and ensure a clean working tree before squashing or rebasing.
Create a timestamped backup branch (git branch backup-$(date +%s)) before destructive operations.
Review staged changes with git diff --cached before finalizing the consolidated commit.
If pre-commit hooks change files during commit, stage and amend (git add . && git commit --amend --no-edit).

Example use cases

Squash the last three local commits into one tidy commit message before opening a pull request.
Rebase your feature branch onto the latest dev branch to resolve conflicts locally and produce a linear history.
Automate repository maintenance scripts to consolidate work-in-progress commits before packaging a release branch.
Recover from a botched rebase by aborting and using reflog to reset to a known good commit.

FAQ

Is it safe to rebase a branch that others are using?

No. Do not rebase branches that have been pushed and shared with collaborators. Only rebase local feature branches to avoid rewriting shared history.

What should I do if a rebase goes wrong?

Run git rebase --abort to stop the rebase, inspect history with git reflog, and restore a known good state with git reset --hard <commit-hash>. Creating a backup branch beforehand reduces risk.