# Git operations

> Draft outline — 2026-08-21. General practice, not tied to any one project's Gitea/GitHub setup.

## Scope

General git operations a coding agent should get right without being told each time: branching,
committing, merging vs. rebasing, and how to recover from the common ways each goes wrong. Anything
specific to one project's hosting setup (branch protection, PR template, CI triggers) belongs in
that project's own KB corpus instead — see this repo's README.

## Outline

- Branching
  - naming conventions and when a new branch is warranted vs. not
  - long-lived vs. short-lived branches
- Committing
  - what makes a commit atomic; when to split or squash
  - message conventions and what a good message actually needs to say
- Merging vs. rebasing
  - when each is appropriate, and the history each produces
  - conflict resolution — reading a conflict marker correctly, not guessing
- Reverting and undoing
  - revert vs. reset vs. checkout — what each does to shared history
  - recovering from a bad rebase or reset (reflog)
- Remotes and collaboration
  - fetch vs. pull, and why the distinction matters under contention
  - force-push: when it's ever appropriate, and how to do it without destroying someone else's work
- Tags and releases
  - lightweight vs. annotated tags
  - what a tag should mean once it's pushed

*(Fill in as it's composed. Each section should end up citable on its own — a chunk boundary, not
just a heading.)*