Merge pull request #23 from entireio/codex/readme-faq · Entire
Merge pull request #23 from entireio/codex/readme-faq
62b687e→main·
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:
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 — smart HTTP, pkt-line, capability negotiation, sideband, relay framing
- 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-packdirectly into targetreceive-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-syncfetches the needed objects into an in-memorygo-gitstore, 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.
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, SECURITY.md, and 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 to report bugs.