Imagine a maintainer moving a small documentation project from a desktop to a laptop. The desktop has a finished draft and a passing link check. The laptop has the check result, an older copy of the draft, and an edit made while offline. A message says “ready to continue.” Which version should the next change build on?

This is an illustrative workflow, not an account of a real incident. The missing detail is the state being handed over. A useful handoff connects the files, the evidence about those files, and the decision the next session is allowed to make.

Name the shared snapshot

Start with an identity the receiver can check. For committed work, record the repository, branch, and full commit ID. If work is uncommitted, also describe the staged changes, unstaged changes, and untracked files that belong to the task. A commit ID alone cannot identify a draft that has never been committed.

Git’s status documentation defines these different working-tree states and provides a stable porcelain format for scripts. It also makes the ignored-file boundary explicit: ignored files are omitted from ordinary status output. If an ignored input is required to reproduce the result, account for it separately through an approved private channel.

For a file-based handoff, keep a manifest of the included relative paths and their content digests. Define the scope and representation: which sources and inputs are included, how line endings are treated, and which generated files are excluded. Otherwise two machines can disagree about a digest without disagreeing about the intended source.

A matching digest establishes content agreement within that scope. It does not establish who approved the work or whether the deployed service uses it. Keep the record’s origin and the production result as separate questions.

Check the receiving copy

Finish the relevant checks, write the handoff record, and stop editing the shared inputs while transferring them. Give each record a unique identity and a reference to its predecessor. Preserve earlier records so that the receiver can tell whether a continuation follows the expected starting point.

Then verify at the receiving machine. The record may arrive before some of its files. The files may arrive before the record. Receiving either one is a reason to inspect the other, not a reason to start changing the project.

Compare the receiving inputs with the named snapshot and inspect unexpected local changes. If something is missing, wait or diagnose the transfer. If something differs, preserve it and find its origin. A sender’s successful check remains evidence about the sender’s tested inputs until the receiver has established that the relevant inputs match.

This can be a lightweight routine for one person alternating machines. It still needs an explicit editing turn: finish on one machine, receive on the other, then resume. A locally written “working” marker cannot guarantee exclusive access when another machine is offline or has not received it.

Keep machine-local state explicit

Decide which files express the project and which files depend on the machine. A source template can be shared while its generated output contains an absolute local path. A build recipe can be shared while the installed runtime, caches, and active processes need checking locally.

For this workflow, keep each clone’s Git database local and transfer committed history through Git. If approved unfinished files also travel through a file-sync service, make their scope explicit. On the receiving clone they may appear as ordinary working-tree changes; review them against that clone’s base before continuing.

Regenerate local outputs from the received source where appropriate. Check the local prerequisites needed for the next action. A configuration file arriving on disk does not establish that a running application loaded it, and a copied log does not establish that a tool is installed.

State these limits in the handoff. The verification note describes how to reuse evidence when its inputs and environment still apply. Repeating every old check wastes effort; carrying a result across an unexamined environment change leaves a gap.

Preserve both sides of concurrent work

If both machines have changed since the same starting point, pause the ordinary handoff. Retain both versions and their base. A later timestamp tells you when a record was written; it does not tell you whether that record includes the other machine’s change.

For committed work, Git’s merge-base documentation defines the ancestry check git merge-base --is-ancestor A B. With both commits available locally, exit status 0 means A is an ancestor of B; status 1 means it is not. Other nonzero results are errors. Check both directions when distinguishing a continuation from diverged history.

For unfinished files, compare each version with the shared base and review the combined intent. Preserve local work before attempting a merge: the Git merge documentation warns that aborting a merge may be unable to reconstruct changes that were uncommitted when it began.

A merge that reports no textual conflict still needs review. One machine might rename a configuration field while the other adds a consumer of its old name. Verify the combined result, then write a new handoff that identifies both predecessors and explains the resolution.

Write the next decision beside the state

Keep the record short enough to read before touching a file. “Finished the article” leaves the next session guessing about review, publication, and the checks already performed. Use fields that turn the progress description into a concrete starting point.

Identity and base
Record ID, predecessor, repository, and commit or shared snapshot.
Included inputs
Changed paths, unfinished files, manifest reference, and machine-local exclusions.
Completed work
The resulting behavior or content, with its review location.
Verification
Checks, results, tested input identity, environment, and evidence location.
Remaining work
Known gaps, unanswered questions, and the condition blocking the next step.
Next action
One specific continuation and the prerequisites it needs.
Authority
What is approved; identify any separate approval needed to publish, deploy, or change access.

For the fictional documentation project, the next action might be “review the received draft in the local preview.” The publication decision stays separate. A progress record can carry existing approval and its scope; its wording cannot create new approval.

Receive before resuming

Make the first minutes on the second machine predictable:

  1. Read the record. Confirm its origin, predecessor, completed scope, and next action.
  2. Match the inputs. Compare the received files with the named snapshot; inspect local changes and missing dependencies.
  3. Resolve divergence. Preserve competing work and review the combined result before accepting a new starting point.
  4. Check local prerequisites. Rebuild machine-dependent outputs and repeat the checks whose conditions have changed.
  5. Take the editing turn. Resume the authorized work, then leave a new record when handing it back.

The handoff is ready when the next session can identify what it received, understand which evidence applies, and choose a permitted next action. That makes returning to the project after a week easier too: the receiving person may simply be your future self.