Troubleshooting the Alpha

Quick triage

dits --version
dits status
dits fsck
dits config --list

Run only the commands relevant to the affected repository. Record the exact version, OS, architecture, filesystem, command, exit status, and smallest redistributable fixture that reproduces the issue.

Installation and command discovery

dits is not found

Confirm the npm global prefix and whether the executable is on your shell's path:

npm config get prefix
command -v dits
dits --version

The published v0.1.5 package contains only Apple-silicon macOS and Windows x64 binaries. Linux, Intel macOS, and Windows ARM64 require a source build. On an unsupported target, the package launcher reports that no matching binary is present; reinstalling the same artifact does not add one. See installation status.

A source build fails

Capture the full Rust diagnostic and toolchain version. Build the active package from the repository root:

rustc -Vv
cargo build --locked --release -p dits

Optional all-feature builds can require platform FUSE libraries. A failure caused by a missing optional dependency is not evidence that a prebuilt binary exists for that platform.

Local repository errors

“Not a Dits repository”

Change to the intended project directory or initialize a new disposable evaluation repository. Do not initialize over unrelated data merely to silence the error.

cd /path/to/evaluation-project
dits status

# Only for a directory you intentionally want to initialize
dits init

A file is absent from the next commit

The current add command requires one or more paths and has no --all flag. Stage the path, inspect status, then commit.

dits add path/to/file
dits status
dits commit --message "Add file"

A restore or merge conflict is incomplete

Preserve the worktree and dits status output before trying another operation. Restore does not yet cover complete merge-conflict resolution. Use an independently verified backup to recover important bytes instead of guessing at internal state.

Remote commands fail

Use local-filesystem clone for a current repository-copy workflow, then place verified copies in separate failure domains with your normal backup tooling.

Integrity and storage

fsck reports an error

dits fsck
dits fsck --verbose

Treat a digest mismatch or missing object as possible corruption. fsck detects problems but has no repair or remote-fetch mode. Preserve the repository, recover from a known-good backup, and compare restored files with an independent standard hash.

The disk is full

dits repo-stats
dits gc --dry-run

The GC dry-run only reports candidates and does not reclaim space. Free space outside the repository or move a complete, backed-up repository to a larger volume. Never delete object files by hand.

High memory or slow ingest

Current large-file ingest is not bounded by the target streaming-memory formula and can hold file-sized and copied buffers. There is no supported memory-limit, disk-buffer, or debug-profile configuration key. Reproduce with a smaller backed-up fixture, monitor the process with OS tools, and report the file size, format, hardware, filesystem, and elapsed time.

Do not compare an observation with a generic throughput promise. Use the benchmark methodology for measured results tied to an environment and commit.

Experimental FUSE mount

mount and unmount appear only in a source build compiled with the optional fuser feature and require an OS FUSE installation. The path is local-only and has no --testoption. If the commands are absent from help, the binary was built without that feature.

cargo build --locked --release -p dits --features fuser
./target/release/dits mount --help

Legacy encryption state

A repository containing the old experimental keystore fails closed before normal operations. Inspect the diagnostic state; do not treat that keystore as complete repository encryption.

dits encrypt-status

# Clears a legacy cached key; it does not enable encryption
dits logout

encrypt-init, login, and change-password intentionally fail without modifying a keystore. See encryption status.

Conflicting lock record

Locks are local advisory metadata, not server-enforced team leases. Inspect the record before releasing it; --force only overrides the owner check in this local store.

dits locks --verbose
dits unlock path/to/file

# Use only after confirming the local record is stale
dits unlock path/to/file --force

Report a reproducible problem

Search GitHub issuesand structured issue forms. A new report should include the exact command and error, Dits version, platform details, expected behavior, and a minimal fixture you have permission to share. Remove secrets, personal data, proprietary media, and private repository paths first.