---
name: git-push
description: "Standardize safe Git push workflows: inspect repository state, configure identity, normalize staging with .gitignore, create or repair local commits (with guarded root-commit rollback), configure remote URLs, and push current branch via SSH or HTTPS with troubleshooting. Use when users ask to initialize repos, prepare clean commits, push to GitLab/GitHub, or resolve auth/push errors."
---

# Git Push

## Workflow

1. Inspect current repository status and risk.
2. Configure local identity if needed.
3. Normalize staging with `.gitignore`.
4. Create or repair commits with a consistent commit-message policy.
5. Configure remote URL and auth strategy.
6. Push current branch and verify results.
7. Return a concise operation report.

## 1) Inspect Repository State

- Run baseline checks:
  - `git status --short --branch`
  - `git rev-parse --abbrev-ref HEAD`
  - `git log --oneline -n 5` (only if `HEAD` exists)
  - `git remote -v`
- Detect whether `HEAD` exists before using `HEAD~1`.
- If unexpected file mutations appear during the run, stop and ask the user before continuing.
- Never discard user changes by default.

## 2) Configure Local Identity

- If missing or explicitly requested, set:
  - `git config --local user.name "<name>"`
  - `git config --local user.email "<email>"`
- Verify with:
  - `git config --local --get user.name`
  - `git config --local --get user.email`

## 3) Normalize Staging With .gitignore

- Ensure `.gitignore` contains generated artifacts when applicable:
  - `output/`
  - `.playwright-cli/`
  - `__pycache__/`
  - `*.pyc`
  - `.DS_Store`
- If ignored files are already tracked, untrack only matching paths first:
  - `git rm -r --cached -- output .playwright-cli __pycache__`
  - `git rm --cached -- '*.pyc' '.DS_Store'`
- Rebuild whole index (`git rm -r --cached . && git add .`) only when user explicitly confirms.
- Re-check staged files before commit.

## 4) Create Or Repair Commits

- Use this commit-message format by default:
  - `<type>(<scope>): <summary>`
- Allowed `type` values:
  - `feat`
  - `fix`
  - `docs`
  - `refactor`
  - `test`
  - `chore`
- `scope` policy:
  - Prefer including scope for multi-module repositories.
  - Prefer `skill/git-push` for this skill.
  - Allow omitting scope when the target area is unclear.
- `summary` policy:
  - Use present tense and one sentence.
  - Keep it short and specific (about 20-60 characters when practical).
  - Do not end with a period.
- If the user provides an explicit commit message, use it as-is.
- Auto-select `type` when user does not specify:
  - Docs-only changes -> `docs`
  - Test-only changes -> `test`
  - Behavior/workflow additions or changes -> `feat`
  - Bug/risk fixes -> `fix`
  - Misc maintenance -> `chore`
- Example messages:
  - `feat(skill/git-push): unify naming and harden safe push defaults`
  - `docs(skill/git-push): document commit message policy`

- Create commit:
  - `git commit -m "<type(scope): summary>"`
- Undo latest commit but keep staged changes:
  - `git reset --soft HEAD~1`
- If only a root commit exists and user asks to undo it, run only after explicit confirmation that history is unpublished:
  - `git rev-list --count HEAD` (must be `1`)
  - `git status --short --branch` (no upstream tracking to remote)
  - `branch=$(git symbolic-ref --short HEAD)`
  - `git update-ref -d "refs/heads/$branch"`
- Avoid destructive commands (`git reset --hard`) unless explicitly requested.

## 5) Configure Remote

- Add origin when missing:
  - `git remote add origin <url>`
- Replace origin URL when needed:
  - `git remote set-url origin <url>`
- Migrate existing origin if required:
  - `git remote rename origin old-origin`
  - `git remote add origin <url>`
- Verify connectivity:
  - `git ls-remote origin`

## 6) Choose Authentication Strategy

- Prefer SSH when server accepts user key.
- Fall back to HTTPS + Personal Access Token (PAT) when SSH fails or policy requires.
- SSH diagnostics:
  - `ssh -T git@<host>`
  - `ssh -vT git@<host>`
- HTTPS push:
  - `git push --set-upstream origin <branch>`
- If prompted for HTTPS password, enter PAT (not account password).

## 7) Push Recipes

- Detect current branch:
  - `branch=$(git symbolic-ref --short HEAD)`
- Default push (new or existing repository):
  - `git push --set-upstream origin "$branch"`
- Push all branches/tags only when user explicitly requests bulk publish:
  - `git push origin --all`
  - `git push origin --tags`
- Post-push verification:
  - `git remote -v`
  - `git branch -vv`

## 8) Failure Handling

- `Permission denied (publickey)`:
  - Confirm key type is supported by remote.
  - Confirm expected fingerprint matches uploaded key.
  - Confirm key is loaded and offered by ssh client.
- `could not read Username`:
  - Use interactive terminal or credential helper.
  - Retry with username + PAT.
- `repository not found`:
  - Confirm remote URL path and account permission.
- `non-fast-forward`:
  - Fetch and rebase/merge per user preference, then retry push.

## 9) Boundaries

- Never force-push by default.
- Never rewrite published history unless user explicitly requests it.
- Never commit secrets or token files intentionally.
- Always report commands run plus resulting branch/remote status.