Eclipse JGit Documentation

The reftable format is a portable binary file format designed for efficient Git reference storage. It is intended as a high-performance alternative to the traditional packed-refs format and loose reference files.

Key characteristics include:

• Efficient Lookups: Supports near constant-time lookup for single references, SHA-1 verification, and namespace scans (e.g., refs/tags/).
• Optimized Storage: Uses variable-sized blocks with prefix compression to reduce disk space. It also allows combining reflog storage with ref storage for small transactions.
• Scalability: Designed to handle repositories with massive numbers of references (e.g., hundreds of thousands) without the linear scan penalties of packed-refs or the inode exhaustion issues of loose references.
• Atomic Operations: Supports atomic pushes with $O(\text{size of update})$ complexity, avoiding the need to rewrite the entire file for small changes.

JGit supports communication with SSH agents using the OpenSSH protocol (the newer SSH2 protocol). It does not support the older SSH1 protocol.

Agent Discovery

JGit discovers agent connectors via the ServiceLoader mechanism using the SPI org.eclipse.jgit.transport.sshd.agent.ConnectorFactory. If no implementation is found, JGit will not attempt to use an SSH agent.

SSH Config for Agents

When using ~/.ssh/config, the following properties are supported:

• AddKeysToAgent: Can be no, yes, ask, confirm, or include key lifetimes. Note that on Windows, Pageant and Win32-OpenSSH do not support confirm or lifetime constraints.
• IdentityAgent: Specifies which agent to use, or none to disable agent use.
• IdentitiesOnly: If set to yes, only keys listed in an IdentityFile (and having a corresponding *.pub file) are considered. This prevents JGit from trying default key names like ~/.ssh/id_rsa.

When implementing or reading reftables, consider the following regarding block management:

• Block Size: Determined by the writer. It must be larger than the longest reference name or log entry. Recommended sizes are powers of two (e.g., 4k, 8k) for filesystem friendliness. Larger sizes (64k) improve compression but increase access costs. The maximum allowed block size is 16777215 bytes (15.99 MiB).
• Alignment: Writers can align blocks at multiples of the block size using padding (NUL bytes).
  • If aligned: The block_size field in the header must specify the alignment.
  • If unaligned: The header must set block_size = 0 and omit padding. Unaligned files with multiple ref blocks must include a ref_index to support fast lookups.
• First Block Exception: The first ref block shares the same block as the file header and is 24 bytes smaller than subsequent blocks.

A reftable file is a structured binary format used for storing Git references and logs. The high-level structure consists of a header, followed by various data blocks (references, objects, logs) and their corresponding indices, ending with a footer.

Standard Reftable Structure:

1. first_block (contains the file header and the first reference block)
2. ref_block* (zero or more reference blocks)
3. ref_index* (zero or more reference index blocks)
4. obj_block* (optional object blocks)
5. obj_index* (optional object index blocks)
6. log_block* (zero or more log blocks)
7. log_index* (zero or more log index blocks)
8. footer (contains metadata and pointers to index positions)

Log-only Reftable Structure: If the file only contains logs, it omits reference and object sections:

1. first_block (contains the file header)
2. log_block*
3. log_index*
4. footer

In log-only files, the first log block immediately follows the header without padding.

first_block {
  header
  first_ref_block
}
ref_block*
ref_index*
obj_block*
obj_index*
log_block*
log_index*
footer

Log blocks (block_type = 'g') are always unaligned and variable in size. They use zlib deflate compression.

Log Block Structure:

1. uint24( block_len ): The inflated size (including the 4-byte header). Use this to preallocate the inflation buffer.
2. zlib_deflate payload containing:
   • log_record+
   • uint24( restart_offset )+
   • uint16( restart_count )

Log Record Format: Log records use a key structured as: ref_name '\0' reverse_int64( update_index ). The reverse_int64 ensures that higher update_index values (more recent) sort first.

Log Record Fields:

• log_type: 0x0 (deletion) or 0x1 (standard git reflog data).
• For log_type = 0x1, the log_data includes:
  • old_id (20-byte SHA-1)
  • new_id (20-byte SHA-1)
  • name (committer name)
  • email (committer email)
  • time_seconds (seconds since epoch)
  • tz_offset (signed minutes from GMT)
  • message (reflog message)

JGit is organized into several modules depending on your requirements:

• org.eclipse.jgit: The core pure Java library for reading/writing repositories and working directories. It has no additional support library dependencies.
• org.eclipse.jgit.ant: Provides Ant tasks based on JGit.
• org.eclipse.jgit.archive: Supports exporting to various archive formats (e.g., zip).
• org.eclipse.jgit.http.apache: Provides Apache HttpClient support.
• org.eclipse.jgit.http.server: A server implementation for the smart and dumb Git HTTP protocol.
• org.eclipse.jgit.lfs: Support for Git Large File Storage (LFS).
• org.eclipse.jgit.lfs.server: Basic LFS server support.
• org.eclipse.jgit.pgm: A command-line interface (CLI) implementing Git commands using JGit.
• org.eclipse.jgit.ssh.apache: SSH protocol client support based on Apache Mina sshd.
• org.eclipse.jgit.ssh.apache.agent: Optional SSH agent support for the Apache SSH client.
• org.eclipse.jgit.ui: A simple UI for displaying the git log.