git-snap-fs

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 18 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## GitSnapFS

GitSnapFS exposes snapshots of a Git repository as a read-only filesystem designed for safe inspection, automated audits, and tooling integration.

### Highlights

- `commits/<revspec>` presents the tree for an individual commit; annotated tags
  and other revspecs are peeled to their commit (`commits/v1.0` works). Likewise
  `trees/<revspec>` peels to a tree, so `trees/HEAD` names HEAD's root tree.
- `branches/` and `tags/` mirror the ref hierarchy: `refs/heads/feature/foo`
  appears as `branches/feature/foo`, with intermediate directories, and each
  ref is a symlink into `commits/` (or `trees/` for tag objects pointing at
  trees). `HEAD` is a symlink into `commits/`.
- Git tree-entry modes are honoured: `100755` blobs are executable (`0o555`),
  `100644` blobs are `0o444`, `120000` blobs are symlinks. Submodule gitlinks
  appear as empty directories.
- The filesystem is strictly read-only and answers requests lazily; updates in
  the underlying repo are surfaced without a pre-scan.
- Directory listings leave `.` and `..` to the kernel, letting path caches stay in userspace.
- We leverage the kernel’s zero-message open/opendir paths (`NO_OPEN_SUPPORT`, `NO_OPENDIR_SUPPORT`) for near-native performance once data is cached.

### Caching: the kernel owns it

gix can only inflate a blob in its entirety, but the kernel asks for file data
in readahead-sized chunks. Instead of keeping a userspace cache, the first
read of a file inflates the blob once, replies with the requested chunk, and
pushes the whole blob into the kernel page cache via `FUSE_NOTIFY_STORE`. Two
details are load-bearing: the push runs on a dedicated notifier thread
(pushing from the request-handling thread deadlocks against the folio locks
of in-flight reads; see `tests/mount_read.rs`), and it is issued in segments
from the *back of the file forwards*, so it meets the kernel's front-to-back
readahead wave head-on instead of trailing it (measured on an 8 MiB file:
8 daemon reads instead of 46). Combined with `FOPEN_KEEP_CACHE` (the kernel
default under zero-message open), subsequent reads — same pass, later opens,
mmap — are served entirely from the page cache, and eviction under memory
pressure is the kernel's call. GitSnapFS retains no blob data of its own; a
dropped push merely means the kernel keeps asking chunk by chunk, each
answered by a full re-inflation.

### Inode scheme and collisions

Inodes are stateless: the top nibble tags the inode class (directory, regular
blob, executable blob, symlink blob, gitlink, ref-tree node), and the low 60
bits are the object id's leading 15 hex digits (or a name hash for ref nodes).
Folding the tree-entry mode into the inode means the same blob reachable as
both `100644` and `100755` gets two distinct inodes, so attributes are always
coherent. See `src/inode.rs` for the full layout.

Truncating object ids to 60 bits admits birthday collisions (probability
≈ n²/2⁶¹ for n objects, i.e. ~4×10⁻⁵ at 10 million objects). Collisions are
*detected, not silent*: inodes resolve through the object database's
unambiguous-prefix lookup, so a collision surfaces as `EIO` plus an error log
rather than another object's content. In addition, each object entry carries
object-id bits 64..128 in the FUSE `generation` field: the kernel treats
`(nodeid, generation)` as the inode identity, so on a collision it evicts the
stale inode instead of serving one object's cached pages or attributes as the
other's, and NFS file handles for the evicted object return `ESTALE`.
Enumerating `commits/` or `trees/` is deliberately unsupported and returns
`ENOTSUP`.

### Requirements

- Linux with FUSE kernel support that advertises `EXPORT_SUPPORT`, `ZERO_MESSAGE_OPEN`, and `ZERO_MESSAGE_OPENDIR`.
- `fusermount`/`fusermount3` (typically provided by `fuse` packages).
- Rust toolchain nightly or stable recent enough to build the dependency graph (`cargo`, `rustc`).

### Quick Start

```bash
cargo run -- --repo path/to/.git --mountpoint /tmp/gitfs
```

The mount exposes the root layout (`commits`, `branches`, `tags`, `HEAD`). Unmount with:

```bash
fusermount -u /tmp/gitfs   # or fusermount3 -u
```

Or by just terminating the process.

### Development

- Design notes live in `codex_spec.md`.
- Formatting and linting are enforced with the following commands:

```bash
  cargo fmt
  cargo clippy --all-targets --all-features -- -D clippy::pedantic -D clippy::style -D clippy::cargo
  ```

- The `clippy.toml` documents unavoidable duplicate crate versions coming from upstream dependencies.
- Please keep the filesystem read-only and avoid libfuse/libgit2 shims; all Git access goes through `gix` and FUSE plumbing through `fuse-backend-rs`.

git-snap-fs

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README