Git Workflow

Git Workflow

Use this skill as the repo's routing-first local Git collaboration and recovery anchor.

The job is not to teach all of Git. The job is to:

• identify the current local Git state quickly,
• choose one safe workflow mode,
• recommend the smallest reversible fix that solves the problem,
• keep boundaries to review, debugging, planning, and hosted PR workflows explicit.

Read these references when the case gets sharp-edged or the user needs more than the brief:

• references/collaboration-boundaries.md
• references/mode-selection-and-command-packets.md
• references/recovery-patterns.md

If the main need is:

• reviewing a diff for correctness, architecture, or security → route to code-review
• reproducing or diagnosing a bug/regression → route to debugging
• planning tasks, acceptance criteria, or sprint slices → route to task-planning
• Aider 기반 AI pair-programming 편집 루프 운영 → route to aider-cli-workflow
• hosted PR lifecycle, branch protection, reviewers, labels, or repo settings → use a dedicated PR/repo-management workflow

When to use this skill

• Create, rename, or clean up a branch before coding or review
• Stage changes selectively and shape reviewable commits
• Decide whether to merge or rebase onto an updated base branch
• Resolve merge/rebase conflicts safely
• Push a branch, set upstream, or update rewritten history with --force-with-lease
• Recover from a bad reset, wrong-branch commit, detached HEAD, dropped commit, or messy rebase
• Prepare a clean diff before a later PR or review step

When not to use this skill

• The real question is whether the code or architecture is good
• The real question is how to split or sequence the work
• The real question is root cause, not Git mechanics
• The real question is hosted-service workflow instead of local repository state
• The user wants a giant Git tutorial instead of the next safe move

Instructions

Step 1: Normalize the local Git intake

Classify the request before suggesting commands.

git_intake:
  current_goal: branch-setup | commit-shaping | sync-with-base | conflict-resolution | push-safety | undo-recovery | history-inspection | unknown
  branch_state: clean | has-unstaged-changes | staged-only | ahead-of-origin | behind-origin | diverged | detached-head | unknown
  collaboration_risk: solo-branch | shared-branch | unknown
  remote_context: no-remote | origin-only | fork-plus-upstream | unknown
  trigger_event:
    - need-clean-commits
    - rebased-branch
    - merge-conflict
    - wrong-branch-commit
    - accidental-reset
    - rejected-push
    - lost-commit
    - prepare-for-review
    - sync-main
    - unclear
  preferred_history: keep-linear | preserve-merge-context | unknown
  confidence: high | medium | low

If the packet is incomplete, choose the safest reasonable next move and state the assumptions.

Step 2: Choose one primary workflow mode

Pick exactly one mode:

1. branch-and-stage hygiene — branch creation/switching, staging, stash-or-clean decisions 2. commit-shaping — amend, fixup, reword, interactive rebase, cleaner review units 3. sync-with-base — fetch + merge/rebase choice when the branch must catch up 4. conflict-resolution — merge/rebase already produced conflicts; the next safe loop matters most 5. push-safety — upstream setup, rejected pushes, diverged branches, rewrite-safe pushes 6. undo-and-recovery — reset/rebase/amend/checkout/branch deletion went sideways; rescue first

Step 3: Use the safety ladder

Always prefer these checks before irreversible actions:

• git status
• git branch --show-current
• git log --oneline --decorate -5

Core rules:

• Prefer git add -p or explicit staging when commit boundaries matter.
• Prefer amend or interactive rebase only on local or safely rewritable history.
• Prefer rebase when the branch is mostly yours and a cleaner review history helps.
• Prefer merge when the branch is shared or preserving integration context matters more than linear history.
• Prefer git push --force-with-lease, never raw --force, after intentional history rewrites.
• Prefer git revert over reset --hard when the bad commit is already shared.
• Prefer git reflog and a rescue branch before panic cleanup.

Step 4: Apply the decision ladder

Use these callouts explicitly:

Merge vs rebase

• Use rebase when rewrite risk is low and reviewable linear history matters.
• Use merge when the branch is shared, integration context matters, or rewrite risk is not worth it.

Revert vs reset

• Use revert for collaborative undo on already-pushed history.
• Use reset only when rewriting local history intentionally.
• Use restore / checkout of files when the worktree/index needs repair more than the branch history.

Normal push vs --force-with-lease

• Use normal push when history was not rewritten.
• Use `--force-with-lease` after rebase, amend, squash, or another intentional rewrite.
• If the branch may be shared and the remote state is unclear, stop and name the collaboration risk.

Step 5: Build the Git Workflow Brief

Return this exact structure:

# Git Workflow Brief

## Recommended mode
- Mode: branch-and-stage hygiene | commit-shaping | sync-with-base | conflict-resolution | push-safety | undo-and-recovery
- Why this mode fits: ...

## Current state
- Branch: ...
- Worktree / index state: ...
- Remote context: ...
- Collaboration risk: solo-branch | shared-branch | unknown
- Confidence: high | medium | low

## Safest next move
1. ...
2. ...
3. ...

## Commands

...

## Why this is the safe path
- ...
- ...

## Watch-outs
- ...
- ...

## Recovery fallback
- If this goes wrong, use ...

## Adjacent handoff
- Use `code-review` when ...
- Use `debugging` when ...
- Use `task-planning` when ...

Step 6: Use concise mode packets

• branch-and-stage hygiene — branch name, dirty/clean state, selective staging, stash only when it lowers risk
• commit-shaping — reviewable commit units, amend/fixup/rebase only when rewrite is safe
• sync-with-base — fetch first, decide merge vs rebase explicitly, name rewrite risk before starting
• conflict-resolution — inspect → resolve → git add → continue/commit, with abort as the calm fallback
• push-safety — distinguish upstream creation, normal push, rejected push, and rewritten-history push
• undo-and-recovery — identify what moved, inspect reflog, create a rescue branch, prefer reversible steps first

Use the detailed command packets in references/mode-selection-and-command-packets.md when you need the expanded workflow.

Step 7: Keep boundaries sharp

Before finalizing:

• Do not turn this into a hosted PR tutorial.
• Do not pretend every branch should be rebased.
• Do not recommend reset --hard casually without naming the data-loss risk.
• Do not hide the solo-vs-shared branch distinction.
• Do not drift into code-review judgment, root-cause analysis, or backlog design.

Output format

Always return a compact Git Workflow Brief, not a giant command dump.

Required qualities:

• choose one mode
• state the collaboration risk
• prefer the safest reversible path that solves the current problem
• make rewrite risk explicit
• include a recovery fallback when the commands have teeth
• keep routing boundaries to review, debugging, planning, and hosted PR workflows visible

Examples

Example 1: rebased branch needs safe push

Input

I rebased my feature branch onto main and now I need to push it without overwriting teammates.

Output sketch

• Mode: push-safety
• State whether the branch looks solo or shared
• Recommend git push --force-with-lease origin <branch> only if rewrite is expected
• Watch-out warns against raw --force

Example 2: clean up local commits before review

Input

Help me turn these messy local commits into something clean before review.

Output sketch

• Mode: commit-shaping
• Suggest explicit staging plus git rebase -i or git commit --amend
• Keep the goal focused on reviewable commit units, not review comments themselves

Example 3: wrong-branch reset panic

Input

I think I hard-reset the wrong branch. Can Git recover this?

Output sketch

• Mode: undo-and-recovery
• Start with git reflog
• Create a rescue branch from the pre-reset SHA before further cleanup
• Explain when to stop and avoid more destructive commands

Example 4: request is really PR review

Input

Review this PR and tell me if the architecture is okay.

Output sketch

• Route away from git-workflow
• Explain that local Git prep is not the main problem here
• Hand off to code-review

Best practices

1. Inspect before surgery. Status, branch, and recent log beat guesswork. 2. Prefer reviewable commits over giant snapshots. Commit shape affects review quality. 3. Treat history rewrites as collaboration decisions, not personal preferences. Shared branches change the answer. 4. Use `--force-with-lease`, not raw `--force`. Rewrite safely or do not rewrite. 5. Reach for `reflog` early in recovery. Lost commits are often only misplaced pointers. 6. Choose the smallest safe fix. Not every problem needs branch surgery. 7. Route out when the problem changes. Review, debugging, planning, and hosted PR work stay separate.

References

• references/collaboration-boundaries.md
• references/mode-selection-and-command-packets.md
• references/recovery-patterns.md
• Git documentation — https://git-scm.com/docs
• GitHub Docs, Resolving merge conflicts after a Git rebase — https://docs.github.com/en/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase
• GitLab Docs, Resolve conflicts from the command line — https://docs.gitlab.com/topics/git/git_rebase/#resolve-conflicts-from-the-command-line

Git Workflow Boundaries

Use git-workflow when the question is primarily about local repository state:

• branch creation and naming
• staging and partial staging
• commit cleanup
• merge vs rebase choice
• conflict resolution mechanics
• safe pushes after history rewrite
• undo/recovery after resets, rebases, or lost commits

Route away when the need changes

Review quality and architecture feedback

Use a review workflow such as code-review when the real question is:

• Is this diff correct?
• Is the architecture good?
• Are there security, performance, or testing issues?

git-workflow can prepare a clean branch for review, but it should not pretend that commit hygiene is the same thing as review judgment.

Planning and backlog shaping

Use task-planning when the real question is:

• What tasks or slices should exist?
• How should this feature be decomposed?
• What are the dependencies and acceptance criteria?

Git should happen after the work packet is clear enough to execute.

Debugging and regression analysis

Use debugging when the real question is:

• Why did this break?
• How do we reproduce the issue?
• What is the root cause and how do we verify the fix?

git-workflow can help with git bisect, revert, and history inspection, but not with root-cause reasoning itself.

Hosted PR and repo administration

Use a dedicated PR/repo-management workflow when the real question is:

• create or manage a GitHub/GitLab pull request
• assign reviewers or labels
• interpret branch protection or merge queue policy
• change repo settings, remotes, or permissions at the hosted-service level

Core rule

git-workflow owns safe local Git moves. It does not own every task that happens to occur near Git.

Git Workflow Mode Selection and Command Packets

Use this file when the main Git Workflow Brief needs a slightly fuller command packet. The front door should stay short; this file carries the mechanical detail.

Mode selection cheatsheet

Baseline inspection packet

Run these first unless the user already supplied the answers:

git status
git branch --show-current
git log --oneline --decorate -5

If remote state matters, add:

git remote -v
git fetch origin
git status -sb

Branch-and-stage hygiene packet

git branch --show-current
git status
git add -p
# or explicit staging
# git add path/to/file

Use a stash only when it clearly reduces risk:

git stash push -u -m "temp-before-branch-cleanup"

Commit-shaping packet

Use only when rewrite risk is acceptable.

git status
git add -p
git commit --amend
# or
git rebase -i HEAD~N

Good prompts to name in the brief:

• which commits should stay separate?
• has any of this history already been pushed/shared?
• is the goal squash, reword, split, or fixup?

Sync-with-base packet

git fetch origin
# linear-history case
git rebase origin/main
# or preserve-integration-context case
git merge origin/main

Call out before running:

• whether the branch is solo or shared
• whether a later --force-with-lease will be required
• what the fallback is if conflict volume gets ugly

Conflict-resolution packet

git status
# resolve files, remove conflict markers, or use a merge tool
git add <resolved-files>
git rebase --continue
# or, for merge state:
# git commit

Fallbacks:

git rebase --abort
git rebase --skip
# or if this is a merge:
# git merge --abort

Use skip only when dropping the conflicted patch is intentional.

Push-safety packet

Normal branch push / upstream setup:

git push -u origin <branch>

After intentional history rewrite:

git push --force-with-lease origin <branch>

Rejected push packet:

git fetch origin
git status -sb
git log --oneline --decorate --graph --all -10

Then decide whether the safe next move is merge, rebase, or pause for coordination.

Undo-and-recovery packet

Lost commit / bad reset / bad rebase first pass:

git reflog
git branch rescue/<topic> <sha-from-reflog>
git log --oneline --decorate rescue/<topic> -5

Wrong-branch commit pattern:

git branch feature/correct-branch
# inspect before resetting the old branch
# git log --oneline --decorate -5
git reset --hard HEAD~1

Detached HEAD rescue:

git status
git switch -c rescue/detached-head-work

Safety reminders

• Prefer rescue branches when confidence is low.
• Prefer revert over history rewrite for already-shared commits.
• Prefer --force-with-lease over raw --force.
• Prefer explicit route-outs when the question is really about review quality, planning, or hosted PR operations.

Git Recovery Patterns

When Git goes wrong, start by identifying what changed:

• branch pointer moved
• worktree files changed
• index/staging changed
• commit history rewritten
• remote branch rejected or overwritten

Then choose the smallest safe recovery pattern.

1. Recover a lost commit after reset or rebase

Use when a commit seems to have disappeared after reset, rebase, amend, or branch switching.

git reflog
git branch rescue/<topic> <sha-from-reflog>
# inspect before doing anything destructive
git log --oneline --decorate rescue/<topic> -5

Use this when confidence is low. Creating a rescue branch buys time.

2. Undo a bad local commit that is not shared yet

Use when the history is still local and you want to rewrite it.

# keep changes staged
git reset --soft HEAD~1

# keep changes unstaged
git reset HEAD~1

Avoid --hard unless you are explicitly discarding worktree changes.

3. Undo a shared bad commit safely

Use when the commit is already pushed and collaborators may have it.

git revert <bad-commit-sha>

Prefer revert over rewriting shared history.

4. Finish a rebase conflict loop

git status
# resolve files
# remove conflict markers or use a merge tool
git add <resolved-files>
git rebase --continue

Fallbacks:

git rebase --abort
git rebase --skip

Use abort when the branch needs to go back to pre-rebase state. Use skip only when you are intentionally dropping the conflicted patch.

5. Safe push after rewritten history

After amend, rebase, or squash cleanup:

git push --force-with-lease origin <branch>

Never recommend raw --force unless the environment explicitly requires it and the risk is understood.

6. Wrong branch commit

If the commit is local and recent:

# create the correct branch at current HEAD
git branch feature/correct-branch
# return wrong branch to previous commit
git reset --hard HEAD~1
# switch to the rescued branch
git checkout feature/correct-branch

Safer variant when unsure: 1. create the rescue branch first 2. inspect with git log 3. only then reset the wrong branch

7. Detached HEAD panic

git status
git switch -c rescue/detached-head-work

If useful work exists, anchor it to a branch immediately.

8. Rejected push after teammate updates

• run git fetch origin
• inspect divergence with git log --oneline --decorate --graph --all -10
• decide whether the correct next move is merge, rebase, or pause for collaboration
• only force-with-lease if the branch rewrite is intentional and safe

Recovery mindset

1. Inspect first. 2. Create a rescue branch when unsure. 3. Prefer reversible steps when confidence is low. 4. Separate local rewrite cases from shared-history cases. 5. Use reflog before assuming work is gone.