okay open a PR

I’ll turn those questions into a clean GitHub issue against this repo, with the README FAQ scope spelled out so it’s easy to pick up. First I’m checking the repo metadata and available issue tooling.

The repo is entireio/gitsync, and there are unrelated untracked docs files in the worktree; I’ll leave those untouched. I’m going to create a focused docs issue now.

Opened the issue: entireio/gitsync#19

I left the existing untracked docs files untouched.

I’ll file a second docs/install issue in the same repo, tying together the executable naming point and the README command mismatch.

Opened it: entireio/gitsync#20

It covers adding installation instructions, explaining the git- executable naming convention, and replacing go run ... README examples with the installed command.

I’ll stash the untracked docs/tutorial artifacts only, so the rest of the worktree stays as-is. Let me confirm the exact files first.

Those are the three untracked docs files. I’m stashing just those paths with a descriptive message now.

Stashed the docs/tutorial files as stash@{0}: On main: stash docs tutorials.

The worktree is clean now.

I’ll switch to main and pull the latest from origin, then I’ll confirm the branch state.

Done. main is checked out and pulled up to origin/main.

Latest commit is b2ab44b Merge pull request #21 from entireio/docs/readme-installation-instructions.

I’ll take a quick look at the current README shape and the docs folder, then I’ll suggest a split that keeps the front page sharp without losing useful detail.

The README is 205 lines and reads more like a mini manual now. I’m sampling the dense sections so the recommendation is grounded in what’s actually there.

My suggestion: keep the README as the “should I use this and how do I run it?” page, and move most operational depth into docs.

I’d split it like this:

README Keeps

• One-sentence product pitch.
• Short “Why this exists” section.
• Installation.
• Quick Start.
• Recommended commands only:
  • git-sync sync
  • git-sync replicate
  • mention plan briefly as preview.
• Short “Behavior at a glance” FAQ, maybe 8-10 tight bullets:
  • smart HTTP only
  • one-way, rerunnable
  • syncs refs and objects
  • supports create/update/delete with flags/policy
  • no background daemon
  • relay first, bounded in-memory fallback
  • not atomic across all refs/remotes
  • SSH unsupported if true
• Links to deeper docs.

Move Out Of README

• Detailed command examples like branch filtering, mapping, tags/prune, protocol v2, memory measuring.
• JSON schema details.
• Most auth resolution details.
• Protocol notes.
• Scaling/memory nuance.
• Advanced/unstable commands.

I’d create a new file: docs/usage.md.

That file would be the “operator manual” and include:

• Command guide:
  • sync
  • replicate
  • plan
  • advanced/unstable commands if worth documenting
• Common examples:
  • branch filtering
  • ref mapping
  • tags
  • prune
  • force
  • protocol selection
  • stats / JSON / memory measurement
• Auth:
  • tokens
  • env vars
  • credential helper
  • bearer tokens
• Operational FAQ:
  • shallow vs historical
  • refs vs objects
  • bidirectional vs one-way
  • create/update/delete
  • partial success / atomicity
  • reruns
  • background behavior
  • SSH support
  • medium repo timing expectations

Then leave docs/architecture.md for “why the system is designed this way” and docs/protocol.md for wire-level guts.

Concretely, README could probably drop from ~205 lines to ~90-120 lines and feel much sharper. The biggest easy wins are moving Examples, JSON Output, most of Auth, and Protocol Notes into docs/usage.md, then replacing them with a compact “More docs” list.

Yes, exactly. No details should be deleted, just relocated.

My plan would be:

• Keep the README focused and shorter.
• Move the detailed examples, JSON contract, auth resolution, protocol notes, and operational FAQ material into docs/usage.md.
• Leave deeper design/protocol material in the existing docs/architecture.md and docs/protocol.md.
• Replace migrated README sections with short summaries plus links, so readers can still find everything.

So the README becomes the front door, and docs/usage.md becomes the full operator guide.

I’ll make the README the front door and create docs/usage.md as the full operator guide, preserving the detailed text rather than thinning it out. After the move I’ll run a quick markdown sanity check with the repo’s usual tools if available.

I’m going to add the new usage doc first, using the existing README wording as the source of truth for the detailed sections. Then I’ll trim the README to point into it.

The detailed usage material is now in docs/usage.md, and the README has been shortened with links back to the full guide. I’m checking the resulting docs shape and diff now.

README is down from 205 lines to 89, while the moved guide carries the detailed content at 137 lines. I’m doing one more pass for link/readability issues and checking the worktree.

I noticed one punctuation change in the migrated text and restored it so the moved wording stays faithful. Final verification is clean on whitespace.

Done. I moved the detailed README usage material into docs/usage.md and shortened README.md to 89 lines.

Kept the details intact in the new usage guide: commands, examples, sync behavior examples, JSON output, auth, and protocol notes. README now keeps the quick start and high-level behavior, then links to docs/usage.md.

Verification: git diff --check -- README.md docs/usage.md passes.

Heads up: there are unrelated untracked config dirs still present (.cursor/, .factory/, .gemini/, .github/hooks/, .opencode/). I left them alone.

I’ll compare our current docs diff against the latest merged commit so we can answer that concretely, not by vibes.

The latest merged README commit is still the base I edited on top of. I’m checking the specific installation/command text now, since that was the risky part from the just-merged change.

No, it doesn’t undo the latest merged README work.

The just-merged installation changes are still present in README.md:

• ## Installation is still there.
• go install entire.io/entire/gitsync/cmd/git-sync@latest is still there.
• The git-sync binary / GOPATH/bin note is still there.
• Quick Start still uses git-sync sync, not go run.
• There are no go run examples left in README.md or docs/usage.md.

What I changed was only moving the longer usage/detail sections out of README into docs/usage.md, then linking to that doc from README.

I’ll put just the README/usage-doc changes on a new codex/ branch, commit them, push, and open the PR. I’ll keep the unrelated untracked config dirs out of it.

Branch is created. I’m staging only README.md and docs/usage.md, then I’ll commit the docs split.

The commit is made. I’m pushing the branch and then I’ll open the PR with a concise summary and the verification note.

Opened the PR: entireio/gitsync#22

It includes one commit, e2728ae Move detailed usage docs out of README, on branch codex/readme-usage-doc. I only staged README.md and docs/usage.md; the unrelated untracked config dirs were left out.

::git-create-branch{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/readme-usage-doc"} ::git-stage{cwd="/Users/rizel/Documents/work/gitsync"} ::git-commit{cwd="/Users/rizel/Documents/work/gitsync"} ::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/readme-usage-doc"} ::git-create-pr{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/readme-usage-doc" url="https://github.com/entireio/gitsync/pull/22" isDraft=false}