Getting Started with Dits

This guide will help you install Dits and create your first repository. Dits is production-ready with 120+ automated tests covering 80+ file formats for creative professionals.

Installation

Dits can be installed using several methods. Choose the one that works best for your environment:

npm install -g @byronwade/dits

Verify installation:

$ dits --version
dits 0.1.2

Choose Your Workflow

Dits supports various creative workflows. Choose the one that matches your needs:

Using Dits Alongside Git

Dits is designed to work seamlessly alongside Git in the same project directory. While both systems can coexist, they serve different purposes and handle different types of files.

Initializing Both Systems

Currently, you need to initialize both Git and Dits repositories separately. Both can coexist in the same project directory:

# Create project directory
mkdir my-creative-project
cd my-creative-project

# Initialize Git (for code and text files)
git init

# Initialize Dits (for large binary assets)
dits init

# Both repositories now coexist:
# .git/ (Git repository)
# .dits/ (Dits repository)

Working with Both Systems

Once both repositories are initialized, you can use both Git and Dits commands as needed:

# Add text/code files with Git
git add src/ package.json README.md

# Add binary assets with Dits
dits add footage/ assets/ renders/

# Commit changes to both
git commit -m "Update source code"
dits commit -m "Add new footage"

# View combined history
git log --oneline  # Code commits
dits log --oneline # Asset commits

Your First Repository

1. Initialize a Repository

Create a new directory for your project and initialize a Dits repository:

mkdir my-video-project
cd my-video-project
dits init

This creates a .dits directory containing the repository data.

2. Add Files

Add your video files or any large binary files:

# Add a specific file
dits add footage.mp4

# Add all files in a directory
dits add raw-footage/

# Add everything
dits add .

3. Check Status

See what's staged and ready to commit:

$ dits status
On branch main

Changes to be committed:
  new file:   footage.mp4
  new file:   raw-footage/scene01.mov
  new file:   raw-footage/scene02.mov

4. Commit Changes

Create a commit with a descriptive message:

$ dits commit -m "Add initial footage"
[main abc1234] Add initial footage
 3 files changed, 2.4 GB added (847 MB stored after dedup)

5. View History

See your commit history:

$ dits log
commit abc1234 (HEAD -> main)
Author: Your Name <you@example.com>
Date:   Mon Jan 15 14:30:00 2025

    Add initial footage

Working with Branches

Branches let you work on different versions of your project simultaneously:

Create a Branch

# Create a new branch
dits branch color-grade

# Switch to the branch
dits switch color-grade

Make Changes and Commit

# Make changes...
dits add .
dits commit -m "Apply color grading"

Merge Back to Main

# Switch to main
dits switch main

# Merge the color-grade branch
dits merge color-grade

Configuration

Set your name and email for commits:

dits config user.name "Your Name"
dits config user.email "you@example.com"

Telemetry Settings

Dits includes optional telemetry to help us improve the product. Unlike Git which has no telemetry, Dits collects anonymized usage statistics when enabled. Telemetry is completely optional and disabled by default.

Learn more about telemetry and privacy in our security documentation.

Virtual Filesystem (VFS)

Mount your repository as a virtual drive for on-demand file access (requires FUSE):

# Mount the repository
dits mount /mnt/dits-project

# Files appear instantly - hydrated on access
ls /mnt/dits-project/footage/

# Unmount when done
dits unmount /mnt/dits-project

Next Steps

• Learn about Core Concepts to understand how Dits works
• Explore the CLI Reference for all commands
• Configure Dits in the Configuration Guide
• Learn about Video Features for media-specific functionality