simplified · Entire

simplified

2023ac3→main·

Soph·2mo ago·5 files·+226 added/-273 removed

Sessions

Transcript data is unavailable for this checkpoint.

Changes

5

Contributing to git-sync

Thank you for your interest in contributing! git-sync is a remote-to-remote Git mirroring tool and library; we welcome contributions from everyone.
Thank you for your interest in contributing to Entire! We welcome contributions from everyone.

Please read our Code of Conduct before participating.

New here? See the README for setup and usage, and docs/architecture.md for the technical overview.

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 on GitHub Issues and wait for maintainer feedback before starting implementation.

Contribution Workflow

  1. Open an issue first
  2. Wait for maintainer feedback -- we may have relevant context or plans
  3. Get approval before starting implementation
  4. Submit your PR referencing the approved issue
  5. Address all feedback including automated review comments
  6. Maintainer review and merge

First-Time Contributors

New to the project? Welcome! Good places to start:

Good First Issues

We recommend starting with:

All feature requests, bug reports, and general issues should be submitted through GitHub Issues.

For security-related issues, see SECURITY.md instead.

Security

If you discover a security vulnerability, do not report it through GitHub Issues. Instead, please follow the instructions in our SECURITY.md file for responsible disclosure. All security reports are kept confidential as described in SECURITY.md.

Contributions & Communication

Contributions and communications are expected to occur through:

How to Contribute

There are many ways to contribute:

Required Information

  1. git-sync version or commit - the binary you ran or git rev-parse HEAD if building from source
  2. Operating system
  3. Go version - run go version
  4. Source and target hosts - what kind of remote (GitHub, GitLab, self-hosted, etc.) — this matters because protocol behavior differs

What to Include

  1. What did you do? - The exact git-sync command you ran (redact tokens)
  2. What did you expect to happen?
  3. What actually happened? - Full error message, and --json output if available
  4. Can you reproduce it? - Every time, or intermittently?
  5. Any additional context? - --stats output, -v verbose log, related issues

Clone and Build

git clone https://github.com/entireio/gitsync.git
mise run test

Making Changes

  1. Create a branch for your changes:

    git checkout -b your-name/feature-name

  2. Make your changes - follow the Code Style guidelines.

  3. Test your changes - see Testing.

  4. Commit with clear, descriptive messages:

    git commit -m "Add feature: description of what you added"

Code Style

Follow standard Go idioms and conventions. For detailed guidance, see the Go Code Style section in CLAUDE.md.

Testing

# Default suite (in-process smart HTTP, no listener required)
mise run test

# With race detection
# Integration tests
mise run test:integration

# Full CI suite
mise run test:ci

Creating an Agent

Entire supports two ways to create agents:

1. Claude Code Agent Personas (Markdown)

These are markdown files that define specialized behaviors for Claude Code (e.g., developer, reviewer, etc.).

   ---
name: my-agent
description: What this agent does
model: opus
color: blue
   ---

# Agent Name
You are a **[Role]** with expertise in [domain].

## Core Principles
   - Principle 1
   - Principle 2

## Process
1. Step 1
2. Step 2

## Output Format
How to structure responses...

2. Coding Agent Integrations (Go)

These are Go implementations that integrate Entire with different AI coding tools (Claude Code, Gemini CLI, OpenCode, Cursor, Factory AI Droid, Copilot CLI, etc.) using the Agent abstraction layer.

  1. Implement the Agent interface in agent/agent.go
  2. Register your agent in the agent registry
  3. Add setup and hook configuration as needed
  4. Ensure session and checkpoint tracking is handled per the abstraction

Troubleshooting

Common Setup Issues

go mod download fails with timeout

# Try using direct mode
GOPROXY=direct go mod download

mise install fails

# Ensure mise is properly installed
curl https://mise.run | sh
# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Community

Join the Entire community:

Additional Resources

Bootstrap Batching Design

Bootstrap Batching

bootstrap currently streams one source pack into one target push. That is good for many initial syncs, but it is not enough for very large single-branch repositories where one initial pack is itself too large for comfortable target-side unpacking and indexing.

This note sketches a batching design for large bootstrap jobs.

Goal

Reduce per-push size and target-side receive-pack / index-pack pressure for very large initial syncs, while preserving the main benefit of bootstrap:

Preferred Model

Model

Use branch checkpoint batching with temporary refs.

High-level idea: Branch checkpoint batching with temporary refs:

  1. Choose a sequence of ancestor checkpoints for a source branch.
  2. Push them oldest to newest into a temporary target ref.
  3. Once the final tip is present, create the real target ref.
  4. Delete the temporary ref at the end.

This gives:

Command Shape

Possible CLI extension:

git-sync bootstrap \
  --target-max-pack-bytes 1073741824 \
  <source-url> \
  <target-url>

Temporary Ref Strategy

git-sync avoids this by:

  1. Identifying the trunk via the source's HEAD symref (see protocol.md) and ordering it first.
  2. Skipping the pack push entirely when a branch tip is already in planStopSet — a subsumed branch. The only command emitted is a single ref-create to point the target ref at the tip.

Restart and Recovery

Batching is only worth doing if failures are restartable.

  1. Detect existing temp refs on target.
  2. Resolve their current hashes.
  3. Resume from the latest completed checkpoint instead of starting from zero.

Current Behavior

Batched bootstrap is invoked via git-sync bootstrap --target-max-pack-bytes.

Current Implementation

The implementation does not parallelize across branches and does not extend the same checkpoint-batching idea to non-empty target incremental relay.