Version 1 of 1 · · razie · in person · Current version

name
d3-f-git
description
Git — a project's code repository: cloning it, item branches, commits, merging into the work branch, and the merge a release makes. Get skills only from /api/v2/skills/d3.
feature
git
concepts
[repo, branch, commit, merge, release]
tags
#skill #feature #d3skill #wip

d3-f-git

Intro

The project's code repository: branches, commits, merging.

A project's code lives in a git repository. Work happens on short item branches cut from the project's work branch (the integration branch, <work>), merged back into it when built; the main branch moves only at a release, on the person's word. The repository, its secret and the branch names are the project's facts. Releasing as a pipeline step: d3-f-pipeline › release_run.

Essentials

  • R-git-1 NEVER commit to, merge into or push main — only a release does that.
  • R-git-2 MUST name the pipeline item (P-n) in every commit message, merges too; code itself carries feature ids and behaviour codes, never P-n.
  • R-git-3 MUST push before you close an item: closed work is on the shared repo, never only in your workspace.
  • R-git-4 NEVER print, log or commit a repo token.
  • R-git-5 NEVER force-push or rewrite history others may have pulled.

Concepts

repo

The project's repository. Also called: the code, the repo. Fields: <repo> and <repoSecret>, the vault secret holding its token — both project facts.

repo_clone

  • Summary: clone with the token from the vault; read the code, not the docs' memory of it.
  • When: at the start of a run, before writing touches or reading code; whoever started you may hand you a fresh clone instead.
  • Needs: <repo> and <repoSecret>; the secret allowed to your role token (d3-f-vault › secret_read).
  • Call: GET /api/v2/vault/<repoSecret> → token into a mode-600 file → git clone https://x-access-token:$(cat <file>)@github.com/<repo>.
  • Rules: R-git-4. Can't clone → say so first thing (board and your person), every run until fixed.
  • Errors: E_SECRET on the vault read → the secret isn't allowed to your role token: ask your person.
  • Gotchas: after cloning, install dependencies before the first test run — an empty dependency folder can hang a suite instead of failing it.

branch

A line of work. Kinds: main (released code), work (the integration branch everyone merges into), item (yours, <work>-<agent>), design (design/P-n, a designer's small style and wording changes).

branch_cut

  • Summary: one item branch per agent, cut from the work branch, never from main.
  • When: before the first commit of a run.
  • Needs: a fresh pull of the work branch.
  • Call: git fetch && git switch -c <work>-<agent> origin/<work>.
  • Rules: R-git-1.
  • Errors: —
  • Gotchas: Why: coders once cut from main while the work branch was ahead, and every merge conflicted.

commit

One recorded change. Fields: message (first line names the item), author.

commit_make

  • Summary: commit as you go, each message naming its item; small decisions as Decided: lines.
  • When: after each coherent step, not once at the end.
  • Needs: the item id you hold.
  • Call: git commit -m "P-n: <what>" (+ Decided: <what, why> lines in the body).
  • Rules: R-git-2, R-git-4.
  • Errors: —
  • Gotchas: —

merge

Bringing your item branch into the work branch.

merge_toWork

  • Summary: pull the work branch, merge yours into it, resolve your own conflicts, test what you touched, push both.
  • When: the build and its tests pass.
  • Needs: board status merging posted (leased like working); the item's touches and any collides/mayCollide items read.
  • Call: git pull origin <work> && git switch <work> && git merge <work>-<agent> → tests you touched → git push origin <work>-<agent> <work> → close with {status: "done", commit: "<sha>"}.
  • Rules: R-git-1, R-git-3, R-git-5. No full suite, no deploy here: those are the release. Unresolved after 20 minutes → post stuck, naming both sides; never guess at another agent's change.
  • Errors: push rejected (non-fast-forward) → pull and merge again, never force.
  • Gotchas: Why: a coder closed five items and died before pushing; the code lived on one laptop only (→ R-git-3). Run suites in the foreground and wait — a backgrounded suite dies with your turn.

merge_designBatch

  • Summary: a design branch goes to a builder as one merge item, on the person's send.
  • When: small style and wording changes made on design/P-n (pushed after every commit) are ready and the person says send.
  • Needs: the batch item; the person's send.
  • Call: git push origin design/P-n → file a merge item for coder agent, ★, askedBy the person.
  • Rules: R-git-1. The designer never merges into the work branch itself.
  • Errors: —
  • Gotchas: —

release

Moving the work branch into main and deploying. Only on the person's word (run the full test and deploy); one release at a time.

release_merge

  • Summary: full suite, fast-forward main to the work branch, deploy, box suite — only on the person's word.
  • When: the person says so; a release item is open.
  • Needs: nobody merging or stuck; the release item.
  • Call: full suite → git switch main && git merge --ff-only <work> && git push origin main → deploy (d3-f-ops › deploy_run) → box suite → note results on the release item.
  • Rules: R-git-5. One deploy per run. A failing suite stops the release; report, don't patch on main.
  • Errors: --ff-only refused → main moved outside a release: stop and tell your person.
  • Gotchas: tag pushes may be refused by a sandbox proxy; say so on the release item rather than retrying.

Errors

  • E_SECRET (403) on the vault read — the repo secret isn't allowed to your role token → ask your person (d3-f-vault › secret_ask). see #repo_clone
  • push rejected (non-fast-forward) — pull and merge again, never force. see #merge_toWork
  • --ff-only refused at release — main moved outside a release → stop, tell your person. see #release_merge