# Merge pull request #23 from entireio/codex/readme-faq `62b687e`→[main](/content/gh/entireio/git-sync/commits/main/index.html)· Soph·2mo ago·3 files·+50 added/-9 removed ## Changes 3 - MCONTRIBUTING.md+6/-6 - MREADME.md+43/-2 - MSECURITY.md+1/-1 ```` 9 unmodified lines 10 11 12 13 13 14 15 16 21 unmodified lines 38 39 40 41 41 42 43 44 9 unmodified lines 54 55 56 57 57 58 59 60 4 unmodified lines 65 66 67 68 69 68 69 70 71 72 30 unmodified lines 103 104 105 106 106 107 108 109 9 unmodified lines ```` ## Before You Code: Discuss First The fastest way to get a contribution merged is to align with maintainers before writing code. Please **open an issue first** using our [issue templates](https://github.com/entireio/gitsync/issues/new/choose) and wait for maintainer feedback before starting implementation. The fastest way to get a contribution merged is to align with maintainers before writing code. Please **open an issue first** using our [issue templates](https://github.com/entireio/git-sync/issues/new/choose) and wait for maintainer feedback before starting implementation. ### Contribution Workflow 21 unmodified lines ## Submitting Issues All feature requests, bug reports, and general issues should be submitted through [GitHub Issues](https://github.com/entireio/gitsync/issues). Please search for existing issues before opening a new one. All feature requests, bug reports, and general issues should be submitted through [GitHub Issues](https://github.com/entireio/git-sync/issues). Please search for existing issues before opening a new one. For security-related issues, see the Security section below. Contributions and communications are expected to occur through: - [GitHub Issues](https://github.com/entireio/gitsync/issues) - Bug reports and feature requests - [Discord](https://discord.gg/jZJs3Tue4S) - Questions, general conversation, and real-time support Please represent the project and community respectfully in all public and private interactions. There are many ways to contribute: - **Feature requests** - Open a [GitHub Issue](https://github.com/entireio/gitsync/issues) to discuss your idea - **Bug reports** - Report issues via [GitHub Issues](https://github.com/entireio/gitsync/issues) (see [Reporting Bugs](#reporting-bugs)) - **Code contributions** - Fix bugs, add features, improve tests - **Documentation** - Improve guides, fix typos, add examples - **Community** - Help others, answer questions, share knowledge ### Clone and Install ```bash git clone https://github.com/entireio/gitsync.git git clone https://github.com/entireio/git-sync.git cd gitsync # Trust the mise configuration (required on first setup) ```` Or build from source: ```bash git clone https://github.com/entireio/gitsync.git cd gitsync git clone https://github.com/entireio/git-sync.git cd git-sync go build -o git-sync ./cmd/git-sync ``` - [docs/protocol.md](docs/protocol.md) — smart HTTP, pkt-line, capability negotiation, sideband, relay framing - [docs/testing.md](docs/testing.md) — test suites and integration coverage ## FAQ ### Does it sync complete Git history or only perform a shallow/partial sync? `git-sync` syncs the complete Git object history required for the selected refs. It does not create a shallow clone. Some planning paths may use filtered fetches, but the target receives the full objects needed for valid refs. ### Is it just refs, or objects as well? Objects as well. Refs are what `git-sync` plans and updates, but it also transfers the commits, trees, blobs, and tags needed for those refs to exist on the target. ### Is it bidirectional? No. `git-sync` is one-way: source remote to target remote. To go the other way you'd run a second invocation with the endpoints swapped. ### Does it support create, update, and delete actions? Yes. It supports creating refs, updating refs, force updates with `--force`, and deleting managed refs with `--prune`. `replicate` can overwrite target refs, but it is relay-only and more restrictive than `sync`. ### How does it scale? `git-sync` has two transfer paths: - **Relay** — pack data streams from source `upload-pack` directly into target `receive-pack`. The local process holds no object graph, so memory stays bounded regardless of repo size. Used when the target supports relay. - **Materialized fallback** — when relay isn't available, `git-sync` fetches the needed objects into an in-memory `go-git` store, plans, then encodes and pushes a packfile. Memory scales with the diff being pushed and is guarded by an explicit object-count limit. Bootstrap can batch large initial syncs to keep this bounded. Planning itself is cheap: ref-only round-trips, plus a `filter tree:0` fetch for ancestry checks when the source advertises filter support. ### How long does it take for a medium-sized repo? It depends on repository size, network speed, and whether the relay path is available. As a rule of thumb, the relay path is bounded by source pack generation + network transfer + target receive-pack time — roughly the time of a `git clone` from the source plus a `git push` of the same pack. The materialized fallback adds local memory work for objects that need inspection. For concrete numbers on your own setup, run the included benchmark tool against a representative repo; see [docs/testing.md](docs/testing.md#benchmarking). ### Does it support SSH? No. `git-sync` supports smart HTTP/HTTPS only. ### Does it run as a daemon or watch for changes? No. `git-sync` is a one-shot CLI/library operation. To sync on a schedule or in response to events, run it from cron, CI, a worker, or another service. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). --- - Resource exhaustion that requires local access to trigger - Issues that cannot be exploited without direct access to the user's machine or to credentials the user already controls Use [GitHub Issues](https://github.com/entireio/gitsync/issues) to report bugs.