# Patch Repo

> Create deterministic git patches (stage/commit) and optionally push safely; writes audit reports under run/skills/patch-repo (scripts/skills/patch-repo.sh). Use when this capability is needed.

- Skill: `tomevault-io/patch-repo` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/patch-repo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/patch-repo/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/patch-repo

---


# SKILL: patch-repo

## Summary

Automate a simple SCM workflow to stage all changes and create a deterministic commit message (update:<tree-hash>) using scripts/skills/patch-repo.sh. By default the script does NOT push to upstream; pass --push to enable pushing. The skill captures stdout/stderr and writes a structured report under run/skills/patch-repo/<timestamp>/ for auditing and troubleshooting.

## When to run

- When local changes are ready to be saved as a patch and optionally pushed upstream.
- Useful for agents that need to persist work by creating commits or preparing patches for review.

## Inputs

- args (array) — arguments forwarded to scripts/skills/patch-repo.sh (supports --push/--no-push; default is no push).


## Outputs

- run/skills/patch-repo/<timestamp>/stdout.txt
- run/skills/patch-repo/<timestamp>/stderr.txt
- run/skills/patch-repo/<timestamp>/report.json — { "commit":"<sha>", "pushed":true|false, "branch":"", "upstream":"", "status":"ok"|"failed", "notes":"" }
- run/skills/patch-repo/<timestamp>/status.txt — git --no-pager status output after completion

## Execution steps

1. Verify inside a git repository and capture working tree state and branch.
2. The skill does not push commits by default; use --push to enable automatic pushing. Ensure the calling agent has permission to push to the target remote/branch and avoid protected branches unless explicitly allowed.
3. Run scripts/skills/patch-repo.sh, capturing stdout/stderr to run/skills/patch-repo/<timestamp>/.
4. After execution, verify that the created commit was successfully pushed; the script will retry pushing up to 3 times before failing. Record each attempt and any errors in the run/skills/patch-repo/<timestamp>/ outputs.
5. If any attempt succeeds, mark pushed=true and write the final report.json and status.txt. If all attempts fail after 3 retries, set status="failed", include details in notes (e.g., last push error), and exit with a non-zero error code so calling agents detect the failure.
6. On non-push failures (e.g., commit creation failed), capture git status and git log -n 5 and include error details in report.json.

## Quality rules & safety

- Do not push to protected branches (main, master, release) without explicit approval.
- This skill does not push by default; ensure protected branches are not targeted by automated runs without explicit consent.
- Do not perform remote network operations; only perform git operations on configured remotes.

## Implementation notes

- Helper script: scripts/skills/patch-repo.sh — commits staged changes and does not push by default (use --push to push). The script re-execs under bash when invoked with sh, performs up to 3 push retries on failure, and exits non-zero if pushes fail so calling agents can detect and react to errors.
- Behavior: stages all changes with `git add .`, creates a deterministic commit `update:<tree-hash>` using `git write-tree` and `git commit`, then attempts to push; when no upstream is configured the first push uses `git push -u origin <branch>`.
- Merge behavior: after a successful push, if the current branch is not `main` or `master`, the script will attempt to merge the pushed branch into the repository's primary branch (detects `origin/main` or falls back to `origin/master`). It will fetch both branches, ensure a clean local copy of the primary branch, and attempt a non-fast-forward merge. On conflicts the script first tries an automated 'theirs' strategy; if that fails it aborts the merge, creates a remote branch `merge/<branch>-into-<main>-<timestamp>` containing the state for manual resolution, and records merge metadata in `run/skills/patch-repo/<timestamp>/report.json` (`merge_attempted`, `merge_result`, `merge_branch`).
- Agent guidance: invoke `sh scripts/skills/patch-repo.sh` (the script will re-exec to bash if needed). Ensure git credentials and remotes are configured (SSH key or token) and that the calling agent has permission to push to `main` or to create merge branches. After execution, parse `run/skills/patch-repo/<timestamp>/report.json` and check `pushed`, `merge_attempted`, `merge_result`, `merge_branch` and `exit_code`; inspect `stdout.txt`/`stderr.txt` for details.
- Partial patches & cherry-picks: if an agent must commit a subset of changes, prepare the index (e.g., `git add -p` or use `GIT_INDEX_FILE`) before invoking this script; consider lower-level git commands for advanced workflows.
- Troubleshooting / manual steps that fixed recent pushes: check `git status -sb` to see upstream and ahead counts, set upstream with `git push -u origin <branch>` when missing, and run `git push` to publish local commits (this was used to publish 5 local commits which updated remote to 355bf26).
- Tuning suggestions: consider adding a dry-run flag, a selective-file mode, or explicit max-retries/config options for agents; ensure CI and agents have network access and appropriate git authentication.

## References

- scripts/skills/patch-repo.sh
- scripts/skills/patch-repo.sh (wrapper)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/p3ngu1nzz) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->