Checkpoint Lab — Collaborative Workflows: Forks, Upstreams, Pull Requests, and Reviewable History

1. Checkpoint scenario — author, fork, reviewer, integrator

You will create an authoritative bare repository and a contributor fork, then use separate working clones for contributor and reviewer/integrator roles. The reviewer will consume the contributor's topic via refs, not through a hosted pull-request UI. You will record enough provenance that a future GitHub/GitLab review system could enforce the same policy.

2. Predictions before any mutation

1. After the contributor runs git fetch upstream, will the local topic branch move automatically?
2. If the authoritative trunk advances after the topic starts, what will git rev-list --left-right --count upstream/trunk...topic-observe reveal?
3. When a reviewer fetches the contributor fork, will that fetch create a local topic branch automatically, or a remote-tracking ref?
4. Will a squash integration preserve a parent edge to the topic commits?

3. Setup: authoritative repo, fork, contributor, reviewer

Git Bash, Bash, or zsh

mkdir git-collab-checkpoint
cd git-collab-checkpoint

git init --bare upstream.git
git clone upstream.git bootstrap
cd bootstrap
git switch -c trunk
git config user.name "Bootstrap Maintainer"
git config user.email "bootstrap@example.invalid"
printf "# Observer Service\n" > README.md
printf "interval=30\n" > observer.conf
git add README.md observer.conf
git commit -m "Initialize observer service"
git push -u origin trunk
cd ..
git --git-dir=upstream.git symbolic-ref HEAD refs/heads/trunk

git clone --bare upstream.git contributor-fork.git
git clone contributor-fork.git contributor
git clone upstream.git reviewer

Preflight: every identity uses .invalid mail, every remote is a local path, and the directory is disposable.

4. Configure fork and authoritative remotes

cd contributor
git config user.name "Contributor"
git config user.email "contributor@example.invalid"
git remote add upstream ../upstream.git
git remote -v
git fetch upstream
git for-each-ref --format='%(refname:short) %(objectname:short)' refs/remotes
git branch -vv

Verify prediction 1: fetch updates remote-tracking knowledge; it does not move a local topic that does not exist yet.

5. Create a reviewable two-commit topic

git switch -c topic-observe upstream/trunk

printf "metrics_endpoint=/metrics\n" >> observer.conf
git add observer.conf
git diff --staged
git commit -m "Expose metrics endpoint for monitoring"

printf "\n## Monitoring\nScrape /metrics from the service.\n" >> README.md
git add README.md
git diff --staged
git commit -m "Document service metrics scraping"

git log --reverse --format='%h %s' upstream/trunk..topic-observe
git diff --stat upstream/trunk...topic-observe

The series is intentionally small and coherent: one operational behavior/configuration change plus documentation.

6. Advance authoritative trunk from the reviewer clone

cd ../reviewer
git config user.name "Reviewer Integrator"
git config user.email "reviewer@example.invalid"
printf "team=observability\n" >> observer.conf
git add observer.conf
git commit -m "Record observer service ownership"
git push origin trunk

cd ../contributor
git fetch upstream
git log --graph --decorate --oneline --all --max-count=12
git rev-list --left-right --count upstream/trunk...topic-observe

Verify prediction 2: one side of the comparison represents authoritative work not in the topic; the other represents topic commits not in authoritative trunk.

7. Synchronize unpublished topic work

git status --short
git rebase upstream/trunk
git log --graph --decorate --oneline --all --max-count=12
git log --oneline upstream/trunk..topic-observe
git diff --check upstream/trunk...topic-observe

If a conflict occurs because your Git version/line endings or manual changes differ, inspect git status, resolve the file, git add it, and run git rebase --continue; use git rebase --abort to restore the original branch state if the resolution is not clear.

8. Publish to the contributor fork

git push --dry-run -u origin topic-observe
git push -u origin topic-observe
git branch -vv
git ls-remote --heads origin topic-observe

Record the exact source OID for provenance:

git rev-parse --verify topic-observe
git rev-parse --verify upstream/trunk

9. Reviewer fetches the contributor proposal as a remote ref

cd ../reviewer
git remote add contributor ../contributor-fork.git
git fetch contributor topic-observe
git branch -r
git log --graph --decorate --oneline --all --max-count=15
git log --oneline trunk..contributor/topic-observe
git diff --stat trunk...contributor/topic-observe

Verify prediction 3: fetch creates/updates a remote-tracking ref such as contributor/topic-observe. The reviewer can inspect the proposal without creating a local topic branch.

10. Produce a compact review evidence report

printf "TARGET=%s\n" "$(git rev-parse trunk)"
printf "SOURCE=%s\n" "$(git rev-parse contributor/topic-observe)"
printf "BASE=%s\n" "$(git merge-base trunk contributor/topic-observe)"
git log --reverse --format='%H %s' trunk..contributor/topic-observe
git diff --check trunk...contributor/topic-observe
git diff --stat trunk...contributor/topic-observe

The report identifies target, source, common base, exact proposal commits, whitespace check, and aggregate delta. A hosting review system can add approvals/check/audit metadata around this Git evidence.

11. Compare merge and squash outcomes without updating shared trunk

git branch review-merge trunk
git branch review-squash trunk

Merge-commit outcome

git switch review-merge
git merge --no-ff contributor/topic-observe -m "Integrate reviewed observability topic"
git rev-list --parents -n 1 HEAD
git log --graph --decorate --oneline --max-count=8

The new integration commit has two parents: previous target tip and topic tip.

Squash outcome

git switch review-squash
git merge --squash contributor/topic-observe
git diff --staged --stat
git commit -m "Add observability metrics endpoint"
git rev-list --parents -n 1 HEAD
git log --graph --decorate --oneline --max-count=8

Verify prediction 4: the squash result is a single-parent commit. Its content can match the proposal delta while its ancestry does not record the topic branch as a parent.

12. Record integration provenance explicitly

In a real hosted workflow, the review system can retain source/target OIDs and approval/check state. In this platform-neutral lab, create a text report outside Git history:

git switch review-merge
{ 
  echo "target_before=$(git rev-parse HEAD^1)"
  echo "topic_tip=$(git rev-parse HEAD^2)"
  echo "integration_commit=$(git rev-parse HEAD)"
  echo "strategy=merge-commit"
} > ../review-provenance.txt
cat ../review-provenance.txt

PowerShell learners can produce the same file with Set-Content/Add-Content. The important design is preserving exact object IDs and strategy, not the shell syntax.

13. Write a lightweight collaboration policy

Create collaboration-policy.txt outside the repositories with at least these decisions:

1. authoritative remote naming and fork naming convention;
2. one topic per coherent operational change;
3. when authors must fetch/synchronize against the target;
4. whether published review commits may be rewritten and how that is communicated;
5. required reviewer/test evidence for normal versus high-risk changes;
6. default integration strategy and exceptions;
7. which rules must be server-enforced when this workflow moves to GitHub/GitLab.

14. Verification checklist

• The authoritative repository and contributor fork are separate bare repositories.
• The contributor clone has origin pointing to the fork and upstream pointing to the authoritative repository.
• The topic contains exactly two coherent proposal commits after synchronization.
• The contributor topic is published to the fork, not directly to authoritative trunk.
• The reviewer inspects contributor/topic-observe as a remote-tracking ref.
• Review evidence records target OID, source OID, merge base, commit list, and diff summary.
• Merge-commit and squash comparison branches have different parent topology.
• No shared authoritative history was force-rewritten.
• A platform-neutral collaboration policy has been written.

15. Cleanup

Git Bash / Bash / zsh

cd ../..
pwd
rm -rf git-collab-checkpoint

PowerShell

Set-Location ../..
Get-Location
Remove-Item -Recurse -Force git-collab-checkpoint

16. Knowledge check

17. What Chapter 08 adds to a production Git operating model

You can now model collaboration without platform magic: authors publish refs, reviewers inspect exact commit sets and deltas, integration ownership moves authoritative refs under policy, and hosting systems add enforceable approvals/checks/audit around those Git facts. You can preserve reviewability while deciding when merge, squash, or linear history fits the operating model.

18. Chapter checkpoint summary

The core collaboration unit is not “a PR button.” It is a well-scoped commit series with known source/target refs, current synchronization evidence, review ownership, and an intentional integration strategy. Hosting platforms can automate and enforce that process, but the underlying Git graph remains inspectable with standard commands.

Authoritative references

• git-fetch
• git-log
• git-rebase
• git-merge
• git-rev-parse
• git-format-patch