docs: add bare repositories recipe#190
Merged
Merged
Conversation
Covers creating, cloning, converting, and using bare repos as local remotes. Includes layout comparison, push-to-non-bare gotcha, and practical multi-developer walkthrough. Closes #172 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove H3 headings for bare and non-bare repositories in Chapter 2 — they interrupted the section flow. Bold lead-in text replaces them. Update cross-reference anchor in the bare-repositories recipe. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add paragraph connecting the structural difference to the practical consequence — bare repos accept pushes because there is no working tree to desynchronize; non-bare repos reject pushes to protect the checked-out files. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace paragraph that used push, branch reference, and staged — terms not introduced until later chapters. Keep the explanation to structure and purpose only. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace one-sentence summary with Alice-and-Bob scenario showing how a push would desync the working tree and cause lost work. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Make explicit that a push only updates the branch reference, not the working tree. Show the broken state with HEAD vs working tree diagram. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Make explicit that Bob pushes directly to Alice's machine (not via a server), so no fetch is needed — the push writes straight into her .git/ directory. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
State explicitly that there is no bare repo, no GitHub, no central server — just two non-bare repos pushing directly to each other. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Chapter 2 now explains why bare repos exist using an Alice-and-Bob scenario: direct push desynchronizes the working tree, bare repo in the middle decouples developers. ASCII diagrams inline, draw.io sources in assets/drawio/ (PNG export pending). Recipe trimmed to cross-reference the chapter for the full explanation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fix missing space, "thumb rule" → "rule of thumb", and restore the line explaining that Git refuses the push to prevent desync. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace push/pull/commit with sends/downloads/snapshots to avoid forward references. Soften "target branch checked out" to "where someone is actively working". Add transition question before the solution diagram. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Push and pull are introduced in Chapter 1, so safe to use here. Replaces sends/downloads/snapshots with push/pull/commit throughout. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Shows how Alice's commit C has B as parent but its snapshot comes from A's files, effectively undoing Bob's work in commit B. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This reverts commit cc7df7d.
Three commit cards (A, B, C) showing file snapshots side by side. Green highlights Bob's change in B, red highlights the same file reverted in C. Legend explains the markers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Color now only at file level: green = changed, red = reverted. Commit cards are all neutral gray so the two meanings don't clash. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Consistent gray for .git/ boxes across both diagrams. Before diagram uses red arrow and desync label. After diagram uses neutral arrows with push/pull labels and "(when ready)" for Alice's pull. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Export all three bare repo diagrams from draw.io at 2x scale. Replace ASCII art in Chapter 2 with image references. The overwrite diagram PNG is ready for use when the text references it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace vague "refuses to accept a push" with concrete explanation of the core.bare config flag and how it controls push acceptance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add ASCII output of a bare repo's config file so the reader can see where the flag lives and what it looks like. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove trailing spaces, reduce .git folder repetition in opening paragraph, replace "checked-out files" with "editable files". Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
chapters/recipes/bare-repositories.mdcovering create, clone, convert, and use bare repos as local remotesCloses #172
Test plan
npm run buildpasses (33 pages, up from 32)Generated with Claude Code