Advanced Commands

Low-level commands for repository maintenance, debugging, and advanced operations.

Advanced Use Only

These commands operate on the internal structure of Dits repositories. Use them carefully and make backups before running destructive operations.

Command	Description	Usage
fsck	Verify repository integrity	dits fsck
gc	Garbage collection	dits gc
prune	Remove unreachable objects	dits prune
pack	Pack objects for efficient storage	dits pack
unpack	Unpack packed objects	dits unpack <pack>
cat-file	Show object contents	dits cat-file <object>
hash-object	Compute hash for data	dits hash-object <file>

Repository Maintenance

dits fsck

Verify the integrity of all objects in the repository. Checks that all hashes match their content.

$ dits fsck

Checking 45,892 chunks...
Checking 1,234 assets...
Checking 89 trees...
Checking 42 commits...

All objects verified. No corruption detected.

# Verbose output
$ dits fsck --verbose
Checking chunk a1b2c3d4... ok
Checking chunk b2c3d4e5... ok
...

# Check specific object
$ dits fsck a1b2c3d4
Object a1b2c3d4: valid

# Show unreachable objects
$ dits fsck --unreachable
Unreachable chunks: 234 (567 MB)
Unreachable assets: 12 (24 KB)
Unreachable commits: 3 (6 KB)

dits gc

Run garbage collection to clean up unnecessary files and optimize the repository.

$ dits gc

Finding unreachable objects...
Found 234 unreachable chunks (567 MB)
Found 12 unreachable assets (24 KB)

Removing unreachable objects... done
Packing loose objects... done
Pruning old packs... done

Freed 567 MB

# Aggressive GC (more thorough)
$ dits gc --aggressive

# Dry run (show what would be collected)
$ dits gc --dry-run
Would remove:
  234 chunks (567 MB)
  12 assets (24 KB)
  3 commits (6 KB)

# Keep objects newer than date
$ dits gc --prune=now  # Remove all unreachable
$ dits gc --prune=2weeks  # Keep if < 2 weeks old

Automatic GC

Dits automatically runs gc --auto after operations that create many loose objects. Manual GC is rarely needed.

dits prune

Remove unreachable objects that are older than the grace period.

$ dits prune
Pruning unreachable objects older than 2 weeks...
Removed 234 objects (567 MB)

# Prune everything unreachable
$ dits prune --expire now

# Dry run
$ dits prune --dry-run

Object Inspection

dits cat-file

Show the contents or type of a repository object.

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

# Show object size
$ dits cat-file -s a1b2c3d4
256

# Show object content
$ dits cat-file -p a1b2c3d4
tree def45678
parent 9f8e7d6c
author Jane Editor <jane@example.com> 1705340400 -0800
committer Jane Editor <jane@example.com> 1705340400 -0800

Add color grading to scene 1

# Show chunk data
$ dits cat-file -p chunk:abc123def
(binary data...)

# Show asset manifest
$ dits cat-file -p asset:xyz789abc
{
  "size": 10737418240,
  "mime_type": "video/mp4",
  "chunks": [
    {"hash": "a1b2c3d4", "offset": 0, "size": 1048576},
    {"hash": "b2c3d4e5", "offset": 1048576, "size": 1048576},
    ...
  ]
}

dits hash-object

Compute the hash of a file or data.

# Hash a file (doesn't store it)
$ dits hash-object footage/scene1.mov
a1b2c3d4e5f6...

# Hash and store
$ dits hash-object -w footage/scene1.mov
a1b2c3d4e5f6...

# Hash stdin
$ echo "test data" | dits hash-object --stdin
f9e8d7c6b5a4...

# Show chunk boundaries
$ dits hash-object --show-chunks footage/scene1.mov
Chunk 1: 0-1048576 (1.0 MB) → a1b2c3d4
Chunk 2: 1048576-2097152 (1.0 MB) → b2c3d4e5
Chunk 3: 2097152-3145728 (1.0 MB) → c3d4e5f6
...
Total: 10,234 chunks

Packing

dits pack

Pack objects for more efficient storage and transfer.

# Pack all loose objects
$ dits pack
Counting objects: 45,892
Compressing objects: 100% (45,892/45,892)
Writing pack: 100%
Created pack abc123 (12.5 GB → 11.2 GB)

# Pack specific objects
$ dits pack --revs
a1b2c3d4
b2c3d4e5
^9f8e7d6c

# Show pack statistics
$ dits pack --stat
Packs: 3
  pack-abc123.pack: 45,000 objects (11.2 GB)
  pack-def456.pack: 892 objects (300 MB)
  pack-ghi789.pack: 100 objects (50 MB)
Loose objects: 234 (567 MB)

dits unpack

Extract objects from a pack file.

# Unpack a pack file
$ dits unpack pack-abc123.pack
Unpacking 45,000 objects...

# Verify during unpack
$ dits unpack --verify pack-abc123.pack

Debugging

dits rev-parse

Parse revision specifications and show their hashes.

# Show commit hash
$ dits rev-parse HEAD
a1b2c3d4e5f6789...

$ dits rev-parse main
a1b2c3d4e5f6789...

# Show tree hash
$ dits rev-parse HEAD^{tree}
def456789abc...

# Show relative commits
$ dits rev-parse HEAD~3
9f8e7d6c5b4a...

dits ls-tree

List the contents of a tree object.

$ dits ls-tree HEAD
100644 asset abc123def footage/scene1.mov
100644 asset def456abc footage/scene2.mov
100644 asset 789xyzabc project.prproj
040000 tree  456abcdef audio/

# Recursive
$ dits ls-tree -r HEAD
100644 asset abc123def footage/scene1.mov
100644 asset def456abc footage/scene2.mov
100644 asset 789xyzabc project.prproj
100644 asset 123abcdef audio/music.wav
100644 asset 456defabc audio/sfx.wav

dits ls-files

Show information about files in the index and working tree.

# Show tracked files
$ dits ls-files
footage/scene1.mov
footage/scene2.mov
project.prproj

# Show staged files
$ dits ls-files --staged
100644 abc123def 0 footage/scene1.mov
100644 def456abc 0 footage/scene2.mov

# Show modified files
$ dits ls-files --modified
footage/scene1.mov

# Show untracked files
$ dits ls-files --others
footage/new-take.mov

Recovery

dits reflog

Show reference log for recovering lost commits.

$ dits reflog
a1b2c3d HEAD@{0}: commit: Current work
f5e4d3c HEAD@{1}: reset: moving to HEAD~3
b2c3d4e HEAD@{2}: commit: Lost commit 3
c3d4e5f HEAD@{3}: commit: Lost commit 2
d4e5f6g HEAD@{4}: commit: Lost commit 1

# Recover lost commit
$ dits reset --hard HEAD@{2}
HEAD is now at b2c3d4e Lost commit 3

dits lost-found

Find unreachable objects that might be recoverable.

$ dits lost-found
Searching for unreachable objects...

Found 5 unreachable commits:
  b2c3d4e commit: Lost work from yesterday
  c3d4e5f commit: Experiment branch
  ...

Found 234 unreachable chunks (567 MB)

# Recover a commit
$ dits branch recovered b2c3d4e