docs: Add Git Workflow Guide for archive collaboration

[isaacschepp]

What and why

GLX's headline differentiator is being "Git-native", but the docs had no guide showing users how to actually use Git workflows for genealogy research — the existing Best Practices section covers only commit hygiene in ~30 lines, and ADR-0004 explains the why but not the how.

This adds a dedicated Git Workflow Guide (docs/guides/git-workflow.md) covering:

• Repository setup — git init after glx init (which creates .gitignore but not the repo), .gitattributes line-ending pinning, private-by-default remotes for living-person data
• The research cycle — one source examined = one commit, glx validate as a pre-commit gate, commit messages that answer what / on what evidence / why
• Branch-based research — hypothesis branches carrying status: speculative assertions, merged as proven when confirmed or deliberately merged as disproven when refuted (negative findings are research data); git worktree + glx diff for comparing branch states
• Collaboration patterns — shared repository for family teams, fork-and-PR maintainer model for societies/one-name studies, PR review as genealogical proof-standard review, a CI validation workflow example
• Merging and conflict resolution — the git merge (same repo) vs glx merge (separate archives) distinction, resolving textual conflicts vs recording evidential conflicts as status: disputed, post-merge glx validate / glx duplicates / glx merge-persons
• History as a research log — git log --follow, git blame, milestone tags, correct-don't-erase
• Scale — Git LFS for media/files/ scans, partial clone for very large archives

The guide is registered in the website nav and /guides/ sidebar, and cross-linked from the Quickstart (Step 9 + Next Steps), Best Practices (Git Workflow section + See Also), and Hands-On CLI Guide (See Also). CHANGELOG entry added under Unreleased → Added.

Related issues

Closes #508

Review focus

Content accuracy of the genealogy-method framing (speculative/proven/disproven branch lifecycle, disputed-status conflict guidance) and whether the git merge vs glx merge distinction is stated correctly. The guide deliberately assumes basic Git knowledge and links out rather than teaching clone/commit.

Testing

• bash scripts/check-links.sh — all 424 relative links OK
• All absolute site links and anchors in the new guide manually verified against the target files (#collaboration, #archive-merging, #vocabulary-governance, #conflicting-evidence, #complete-evidence-chains, #id-generation, CLI reference pages)
• npm run build (VitePress) fails locally on unmodified main with the same estree-walker ESM error under Node 24.14.1, so the local build could not verify dead links either way — relying on CI's build for that
• Release asset name in the CI example (glx_Linux_x86_64.tar.gz) checked against .goreleaser.yml's name_template
• glx init behavior (creates .gitignore/README.md, does not run git init) checked against glx/init_runner.go

Breaking changes

None — documentation only.

[cloudflare-workers-and-pages]

Deploying genealogix with    Cloudflare Pages

Latest commit:	8586ac3
Status:	✅  Deploy successful!
Preview URL:	https://58dca4d2.genealogix.pages.dev
Branch Preview URL:	https://docs-git-workflow-guide.genealogix.pages.dev

View logs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds a dedicated documentation guide explaining practical Git workflows for collaborating on GLX archives (branch-based research, collaboration/review patterns, and merge/conflict handling), and wires it into the docs navigation and related guides.

Changes:

• Add new guide: docs/guides/git-workflow.md (setup, research cycle, branching, collaboration, merge/conflict resolution, scale tips).
• Link the new guide from Quickstart, Best Practices, Hands-On CLI Guide, and add it to the VitePress nav/sidebar.
• Add an Unreleased changelog entry (currently needs a fix; see PR comments).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
website/.vitepress/config.js	Adds “Git Workflow” to guides nav/sidebar items.
docs/quickstart.md	Cross-links to the new Git Workflow guide from Quickstart steps/next steps.
docs/guides/hands-on-cli-guide.md	Adds “Git Workflow Guide” to the guide’s suggested next reads.
docs/guides/git-workflow.md	New, comprehensive Git workflow documentation for GLX archives.
docs/guides/best-practices.md	Adds “See also” + link to the deeper Git Workflow guide.
CHANGELOG.md	Adds an Unreleased entry (currently conflates two entries; needs splitting).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[noahbjohnson]

Really nice guide — the conceptual framing is the strong part, and I checked the git merge vs glx merge distinction, the "why conflicts are rare" reasoning, and all the links/anchors against the code and they hold up.

I did run every command and YAML block through a real glx init archive, though, and three of the copy-pasteable snippets break when a reader actually uses them. Since the whole point of the guide is that people copy these, I'd treat them as blockers before merge.

---

1. The CI workflow's checksum step fails on every run. In the validate.yml example, the release asset is downloaded and renamed to glx.tar.gz:

curl -fsSL -o glx.tar.gz "$base/glx_Linux_x86_64.tar.gz"

…but the verification line then asks sha256sum to check the original name, which no longer exists on disk:

grep ' glx_Linux_x86_64.tar.gz$' checksums.txt | sha256sum -c -
# sha256sum: glx_Linux_x86_64.tar.gz: No such file or directory  → exit 1

Because GitHub Actions runs steps under bash -eo pipefail, that non-zero exit fails the job — so anyone who copies this workflow gets a permanently red gate, regardless of version or network. The simplest fix is to stop renaming: download and extract under the checksum's own name.

curl -fsSL -o glx_Linux_x86_64.tar.gz "$base/glx_Linux_x86_64.tar.gz"
grep ' glx_Linux_x86_64.tar.gz$' checksums.txt | sha256sum -c -
tar -xzf glx_Linux_x86_64.tar.gz -C .bin glx

2. The merge-conflict Person snippet is invalid GLX. The "When They Happen Anyway" example shows a top-level names: list as a sibling of properties:. The Person schema is additionalProperties: false and only allows properties and notes, so glx validate rejects it:

additional properties 'names' not allowed

This one is doubly unfortunate because the same guide wires glx validate into a pre-commit hook a few sections earlier — so a reader who resolves the conflict exactly as shown then can't commit. Worth reshaping the snippet so the name lives under properties.name (with value / fields.given / fields.surname) and the conflict markers sit around occupation, matching the real examples elsewhere in the docs.

3. The Research Cycle's git add fails on a fresh clone. glx init creates the entity directories empty, and Git doesn't track empty directories, so the initial commit never records persons/, events/, citations/, or sources/. On the author's own machine those dirs exist, so git add persons/ events/ … works — but a collaborator who clones the archive (the exact workflow the Remote Backup and Collaboration sections encourage) hits:

fatal: pathspec 'persons/' did not match any files   # exit 128, nothing staged

Swapping that line for git add -A (or git add ., to match the Setting Up section) fixes it. Separately, it might be worth having glx init drop .gitkeep files so the layout survives a clone — but that's a follow-up, not needed for this PR.

---

Everything else I threw at it came back clean — the .gitattributes block, the default-archive validation, glx diff --short, the CHANGELOG entry, and the nav/sidebar wiring all work as written. Happy to help with the reshaped Person snippet if useful.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.