brokk-git-usage
Perform local git operations — branching, staging, committing — without modifying existing history.
SKILL.mdskills/brokk/brokk-git-usage/SKILL.md
GitHubGit Usage
Purpose
Local git operations for version control during implementation: branch creation, staging, committing, and history inspection. Scoped to local, forward-only operations that never modify existing git history.
When to Use
- When starting implementation work on a new task — create a branch first.
- When staging and committing completed work.
- When inspecting repository state (status, diff, log) to understand current changes.
- Alongside any other implementation skill when changes need to be committed.
- When the requesting agent asks for commit history or branch information.
Workflow
Create a branch.
- Create a feature, fix, or refactor branch:
git checkout -b <type>/<name>orgit switch -c <type>/<name>. - Use
feature/,fix/,refactor/prefix with kebab-case description (e.g.,feature/add-user-auth,fix/login-redirect).
- Create a feature, fix, or refactor branch:
Implement and stage changes.
- Make focused code changes for a single logical concern.
- Run
git statusandgit diffto review all changes. - Stage individual files by name:
git add src/auth.ts src/auth.test.ts. - Use
git rmfor deletions andgit mvfor renames. - Review
git diff --cachedbefore committing.
Verify and commit.
- Run tests (and linter if present); fix failures before committing.
- Commit:
git commit -m "<type>: <description>"— types:feat:,fix:,refactor:,test:,docs:,release:. - Subject line: imperative, lowercase, no period, ~50 characters; never WIP-style ("wip:", "todo:") — use real, descriptive messages. Add a body for non-trivial commits explaining why (blank line separator, wrapped at 72).
Repeat and report.
- Stage and commit each concern separately; re-verify tests before each commit.
- Summarize the branch, commit count, and messages to the requesting agent.
Quality Criteria
- Each commit is atomic — one logical change with a conventional, descriptive message (types:
feat:,fix:,refactor:,test:,docs:,release:). - Tests pass at every commit (full test suite, not just final state).
- All changes committed to a feature, fix, or refactor branch — never directly to
mainordevelop. - Staged diff reviewed before every commit.
- Clean tree: no secrets (API keys,
.envfiles), no junk (.DS_Store,node_modules/,dist/, build artifacts), no commented code, no large binaries.
Anti-Patterns
- History modification (
--amend,rebase,reset,filter-branch): Rewrites or destroys commits — use a new commit instead. - Blind staging (
git add .orgit add -A): Risk committing unintended files or secrets; stage by name after reviewinggit statusandgit diff. - Committing secrets or junk: API keys,
.envfiles,.DS_Store, build artifacts — review the staged diff and verify.gitignorebefore every commit. - Shell operators in git commands (
git add . && git push,git commit -m "…" || echo error): Chaining with&&,||,;, pipes,$(), or redirection can bypass safeguards; run each git command individually. - Remote or shared-state operations (
push,pull,fetch,merge,cherry-pick,revert): These affect shared repositories or rewrite history — defer to the requesting agent for orchestration decisions. Create commits on the current branch only.