#bit

Warning: This is an experimental implementation. Do not use in production. Data corruption may occur in worst case scenarios. Always keep backups of important repositories.

#Install

# One-line install
curl -fsSL https://raw.githubusercontent.com/mizchi/bit-vcs/main/install.sh | bash

# Or install via MoonBit toolchain
moon install mizchi/bit

#Subdirectory Clone

# Using @user/repo/path shorthand
bit clone mizchi/bit-vcs:src/vfs

# Or paste GitHub browser URL
bit clone https://github.com/user/repo/tree/main/packages/core

# Single file download
bit clone https://github.com/user/repo/blob/main/README.md

#Standard Git Commands

bit clone https://github.com/user/repo
bit checkout -b feature
bit add .
bit commit -m "changes"
bit push origin feature

#Local Collaboration (bit issue / bit pr)

# Initialize PR / Issue metadata once per repository
# `bit pr init` / `bit issue init` ask before creating `.git/hub/policy.toml`
# and before adding `refs/notes/bit-hub` sync settings to `remote.origin.*`.
bit pr init

# Force prompts on/off when scripting
BIT_HUB_INIT_PROMPT=1 bit issue init
BIT_HUB_INIT_PROMPT=0 bit pr init

# Local issues
bit issue create --title "Cache invalidation bug" --body "status view stays stale"
bit issue list --open             # top-level issues, with sub-issue counts
bit issue list --tree             # parent/child tree
bit issue list --all              # flat list including children
bit issue list --parent <issue-id>

# Local pull requests
bit pr create --title "Fix cache invalidation" --body "refresh status after write" \
  --head feature/cache-fix --base main
bit pr list --open
bit pr review <pr-id> --approve --commit <commit-hex>
bit pr merge <pr-id>

# Optional relay sync for PR / Issue metadata
bit relay sync push <remote-url>
bit relay sync fetch <remote-url>

#Compatibility

• Hash algorithm: SHA-1 only.
• SHA-256 repositories and --object-format=sha256 are not supported.
• Git config: reads global aliases from ~/.gitconfig (or GIT_CONFIG_GLOBAL) only.
• Shell aliases (prefixed with !) are not supported.

#Implemented Commands (108)

init add diff diff-files diff-index ls-files tag branch checkout switch
commit log show reflog reset update-ref update-index status merge rebase
clone push fetch pull mv notes stash rm submodule worktree config show-ref
for-each-ref rev-parse symbolic-ref cherry-pick remote cat-file hash-object
ls-tree write-tree commit-tree receive-pack upload-pack pack-objects
index-pack format-patch describe gc clean sparse-checkout restore blame
grep shell rev-list bisect diff-tree read-tree fsck am apply bundle cherry
revert prune pack-refs mktree shortlog verify-pack unpack-objects
maintenance range-diff show-branch repack multi-pack-index pack-redundant
send-pack request-pull merge-base var stripspace ls-remote fmt-merge-msg
patch-id count-objects name-rev update-server-info check-ref-format mktag
interpret-trailers column merge-tree merge-file fast-import fast-export
verify-tag fetch-pack credential difftool rerere mailinfo archive
check-attr check-ignore show-index get-tar-commit-id verify-commit annotate

#Git-Compat Test Results

#Standalone Test Coverage

• repository lifecycle and core porcelain: init, status, add, commit, branch, checkout/switch, reset, log, tag
• transport-style workflows in standalone mode: clone, fetch, pull, push, bundle
• plumbing used by normal flows: hash-object, cat-file, ls-files, ls-tree, write-tree, update-ref, fsck
• feature flows: local collaboration (pr, issue, debug, relay), ai (rebase, merge, cherry-pick, revert, commit; rebase-ai is alias), mcp, hq

#Explicitly Unsupported In Standalone Mode

• signed commit modes (commit -S, commit --gpg-sign)
• interactive rebase (rebase -i)
• reftable-specific paths (clone --ref-format=reftable, update-ref on reftable repo)
• cloning from local bundle file (clone <bundle-file>)
• SHA-256 object-format compatibility paths (hash-object -w with compatObjectFormat=sha256, write-tree on non-sha1 repo)
• cat-file --batch-all-objects with %(objectsize:disk)
• unsupported option sets for index-pack and pack-objects

#Where Git Fallback Exists

• Main bit command dispatch in src/cmd/bit/main.mbt does not auto-delegate unknown commands to system git.
• Git fallback/delegation is implemented in the shim layer tools/git-shim/bin/git.
  • The shim delegates to SHIM_REAL_GIT by default.
  • CI git-compat (.github/workflows/ci.yml) runs upstream git/t via this shim (SHIM_REAL_GIT, SHIM_MOON, SHIM_CMDS).

#Unimplemented Features

#Fundamentally Missing

#Porcelain Commands - Missing Options

#Plumbing Commands - Missing Options

#repack Test Coverage (t7700: 25/47)

#Environment Variables

• BIT_BENCH_GIT_DIR: override .git path for bench_real (vfs benchmarks).
• BIT_PACK_CACHE_LIMIT: max number of pack files to keep in memory (default: 2; 0 disables cache).
• BIT_RACY_GIT: when set, rehash even if stat matches to avoid racy-git false negatives.

#Extensions

#Fs - Virtual Filesystem

let fs = Fs::from_commit(fs, ".git", commit_id)
let files = fs.readdir(fs, "src")
let content = fs.read_file(fs, "src/main.mbt")

#Kv - Distributed KV Store

let db = Kv::init(fs, fs, git_dir, node_id)
db.set(fs, fs, "users/alice/profile", value, ts)
db.sync_with_peer(fs, fs, peer_url)

#PR / Issue Metadata (Hub library)

let hub = Hub::init(fs, fs, git_dir)
let pr = hub.create_pr(fs, fs, "Fix bug", "...",
  source_branch, target_branch, author, ts)

#License