Skip to main content
D
Dits
Documentation

Internals & Plumbing

Low-level commands for advanced operations, scripting, and understanding how Dits works under the hood. These are the building blocks that power higher-level commands.

Object Types

Dits stores four types of objects:

Chunk

Raw content data. Files are split into chunks using content-defined chunking. Each chunk is identified by its SHA-256 hash.

Blob

File metadata + ordered list of chunk references. A blob represents a complete file as an ordered sequence of chunks.

Tree

Directory structure. Contains references to blobs (files) and other trees (subdirectories) with names and permissions.

Commit

Snapshot metadata. Points to a tree and contains author, message, timestamp, and parent commit reference(s).

Inspecting Objects

dits cat-file

Display object content or type:

# Show object type
$ dits cat-file -t abc1234
commit

# Show object size
$ dits cat-file -s abc1234
287

# Show raw content
$ dits cat-file -p abc1234
tree def5678
parent 0001234
author Your Name <you@example.com> 1702300000 -0500
committer Your Name <you@example.com> 1702300000 -0500

Add new feature

# Show blob content
$ dits cat-file blob 789abcd
[file content appears here]

# Show tree
$ dits cat-file -p def5678
100644 blob 111aaa    README.md
100644 blob 222bbb    package.json
040000 tree 333ccc    src

dits hash-object

Compute hash of content:

# Hash file content (don't store)
$ dits hash-object myfile.txt
abc123def456...

# Hash and write to object store
$ dits hash-object -w myfile.txt
abc123def456...

# Hash from stdin
$ echo "hello" | dits hash-object --stdin
2cf24dba5fb0a30e...

Reference Commands

dits show-ref

# List all refs
$ dits show-ref
abc1234 refs/heads/main
def5678 refs/heads/feature/new-ui
111aaa refs/remotes/origin/main
222bbb refs/tags/v1.0.0

# Show specific ref
$ dits show-ref refs/heads/main
abc1234 refs/heads/main

# Check if ref exists
$ dits show-ref --verify refs/heads/main && echo "exists"

dits rev-parse

# Resolve ref to commit hash
$ dits rev-parse HEAD
abc1234def5678...

$ dits rev-parse main
abc1234def5678...

# Resolve relative refs
$ dits rev-parse HEAD~3
older-commit-hash...

# Show git directory
$ dits rev-parse --dits-dir
/path/to/project/.dits

# Check if in repo
$ dits rev-parse --is-inside-work-tree
true

dits update-ref

# Update a ref (careful!)
$ dits update-ref refs/heads/feature/branch abc1234

# Create new ref
$ dits update-ref refs/heads/new-branch HEAD

# Delete ref
$ dits update-ref -d refs/heads/old-branch

Chunk Operations

dits chunk-info

Dits-specific command to inspect chunks:

# Show blob's chunks
$ dits chunk-info README.md
Blob: abc1234
Total chunks: 3
Total size: 4,567 bytes

Chunk 1: def567 (1,234 bytes)
Chunk 2: 123abc (2,048 bytes)
Chunk 3: 456def (1,285 bytes)

# Show chunk details
$ dits chunk-info --chunk def567
Hash: def567890abcdef...
Size: 1,234 bytes
Reference count: 5
Used by:
  - README.md (blob abc1234)
  - docs/intro.md (blob xyz789)
  - ...

# Show file chunking preview
$ dits chunk-info --preview large-file.bin
Estimated chunks: 1,234
Average size: 64 KB
Algorithm: fastcdc

dits verify-chunks

# Verify chunk integrity
$ dits verify-chunks
Checking 12,345 chunks...
  Verified: 12,345
  Corrupted: 0
  Missing: 0
All chunks OK.

# Verify specific file
$ dits verify-chunks -- video.mov
Checking 456 chunks for video.mov...
All chunks OK.

# Fix corrupted chunks (re-fetch from remote)
$ dits verify-chunks --fix
Checking 12,345 chunks...
  Corrupted: 2
  Re-fetching from origin...
  Fixed: 2
All chunks OK.

Index Operations

dits ls-files

# List tracked files
$ dits ls-files
README.md
package.json
src/index.ts
src/utils.ts

# Show staged files
$ dits ls-files --stage
100644 abc123 0  README.md
100644 def456 0  package.json

# Show modified
$ dits ls-files --modified

# Show untracked
$ dits ls-files --others

# Show ignored
$ dits ls-files --ignored

dits update-index

# Add file to index
$ dits update-index --add myfile.txt

# Remove from index
$ dits update-index --remove myfile.txt

# Refresh index (check for changes)
$ dits update-index --refresh

# Assume unchanged (skip in status)
$ dits update-index --assume-unchanged bigfile.bin

# Undo assume unchanged
$ dits update-index --no-assume-unchanged bigfile.bin

Low-Level Commit

# Create tree from index
$ dits write-tree
tree-hash-abc123...

# Create commit manually
$ dits commit-tree tree-hash-abc123 -p HEAD -m "Manual commit"
commit-hash-def456...

# Update HEAD to new commit
$ dits update-ref HEAD commit-hash-def456

Debugging

# Enable debug logging
$ DITS_DEBUG=1 dits status

# Trace all operations
$ DITS_TRACE=1 dits push origin main

# Show internal stats
$ dits count-objects
count: 12,345
size: 2.3 GB
chunks: 45,678
in-pack: 40,000
packs: 3

# Check repository health
$ dits fsck
Checking objects...
Checking connectivity...
All objects OK.

Related Topics