CLI Reference

Remote Commands

A roadmap design for synchronizing your local repository with remote servers.

Roadmap — networked sync is not yet functional

fetch, pull, and push over a network are placeholders— the wire protocol that transfers chunks is not wired up yet, so no data moves to or from a remote server. The commands, options, and example output below describe the planned design. What works today is the local VCS and local-filesystem clone/push (a path on the same machine). See the roadmap for status.

Command	Description	Usage
fetch	Download objects and refs from remote	dits fetch [remote]
pull	Fetch and integrate with local branch	dits pull [remote] [branch]
push	Update remote refs and objects	dits push [remote] [branch]
remote	Manage remote repositories	dits remote <command>

dits fetch

Download objects and refs from a remote repository without merging. Updates remote-tracking branches so you can see what changed before integrating.

Synopsis

dits fetch [options] [remote] [refspec...]

Options

--all            Fetch all remotes
--prune, -p      Remove stale remote-tracking branches
--tags           Fetch all tags
--depth          Limit fetch to specified depth
--dry-run        Show what would be fetched
--verbose, -v    Be verbose

Examples

# Fetch from default remote (origin)
$ dits fetch
Fetching origin...
remote: Counting objects: 45, done
remote: Finding chunks: 12,456 (8.5 GB)
Receiving objects: 100% (45/45), done
From https://example.com/project
   a1b2c3d..f5e4d3c  main       -> origin/main
 * [new branch]      feature    -> origin/feature

# Fetch from all remotes
$ dits fetch --all

# Fetch specific branch
$ dits fetch origin feature/audio

# Prune deleted remote branches
$ dits fetch --prune
From https://example.com/project
 - [deleted]         origin/old-feature

# See what would be fetched
$ dits fetch --dry-run
Would fetch:
  main: a1b2c3d → f5e4d3c (12 new chunks)
  feature: new branch (8,456 chunks)

dits pull

Fetch from remote and integrate changes into the current branch. Combines fetch and merge (or rebase) in one command.

Synopsis

dits pull [options] [remote] [branch]

Options

--rebase         Rebase instead of merge
--no-rebase      Merge even if pull.rebase is set
--ff-only        Only fast-forward
--no-ff          Create merge commit
--autostash      Stash changes before pull
--verbose, -v    Be verbose

Examples

# Pull from tracked branch
$ dits pull
Fetching origin...
Updating a1b2c3d..f5e4d3c
Fast-forward
 footage/scene1.mov | modified
 1 file changed

# Pull with rebase
$ dits pull --rebase
Fetching origin...
Rebasing (1/2): Local commit 1
Rebasing (2/2): Local commit 2
Successfully rebased onto origin/main

# Pull specific remote/branch
$ dits pull origin feature/audio

# Auto-stash local changes
$ dits pull --autostash
Stashing local changes...
Fetching origin...
Updating a1b2c3d..f5e4d3c
Applying stashed changes...

Delta Transfer (planned)

The planned design transfers only the chunks a remote is missing, so pulls would be far faster than downloading everything. This delta transfer is roadmap — it is not implemented yet.

dits push

Upload local commits and objects to a remote repository. Only transfers chunks that don't already exist on the remote.

Synopsis

dits push [options] [remote] [refspec...]

Options

--all            Push all branches
--tags           Push all tags
--force, -f      Force push (overwrite remote)
--force-with-lease  Safer force push
--delete         Delete remote branch
--set-upstream, -u  Set upstream for branch
--dry-run, -n    Show what would be pushed
--verbose, -v    Be verbose

Examples

# Push to tracked branch
$ dits push
Pushing to origin...
Uploading chunks: 100% (156/156) [1.5 GB]
To https://example.com/project
   a1b2c3d..f5e4d3c  main -> main

# Push and set upstream
$ dits push -u origin feature/audio
Branch 'feature/audio' set up to track 'origin/feature/audio'
Pushing to origin...
To https://example.com/project
 * [new branch]      feature/audio -> feature/audio

# Push specific branch
$ dits push origin main

# Push all branches
$ dits push --all

# Push tags
$ dits push --tags

# Delete remote branch
$ dits push origin --delete old-feature
To https://example.com/project
 - [deleted]         old-feature

# See what would be pushed
$ dits push --dry-run
Would push:
  main: a1b2c3d → f5e4d3c
  Chunks to upload: 156 (1.5 GB)
  Already on remote: 10,078

Force Push Warning

Avoid --force on shared branches. It overwrites remote history and can cause data loss. Use --force-with-leasefor safer force pushes that fail if someone else pushed first.

dits remote

Manage the set of tracked remote repositories. Add, remove, rename, and inspect remote connections.

Synopsis

dits remote [-v]
dits remote add <name> <url>
dits remote remove <name>
dits remote rename <old> <new>
dits remote set-url <name> <url>
dits remote show <name>

Examples

# List remotes
$ dits remote -v
origin  https://example.com/team/project (fetch)
origin  https://example.com/team/project (push)
backup  https://backup.example.com/project (fetch)
backup  https://backup.example.com/project (push)

# Add a remote
$ dits remote add upstream https://github.com/original/project

# Show remote info
$ dits remote show origin
* remote origin
  Fetch URL: https://example.com/team/project
  Push URL: https://example.com/team/project
  HEAD branch: main
  Remote branches:
    main           tracked
    feature/audio  tracked
    feature/color  tracked
  Local branches configured for 'dits pull':
    main merges with remote main
  Local refs configured for 'dits push':
    main pushes to main (up to date)

# Change remote URL
$ dits remote set-url origin https://new.example.com/project

# Remove a remote
$ dits remote remove backup

Transfer Progress (planned)

In the planned networked design, Dits would show detailed progress during transfers. The output below is illustrative — networked transfer is not implemented yet:

$ dits push
Pushing to origin...

Analyzing commits... 3 commits
Computing delta... 156 new chunks (1.5 GB)
Compressing chunks... done

Uploading: [====================] 100% (156/156)
  Transferred: 1.5 GB
  Speed: 125 MB/s
  Time: 12 seconds

To https://example.com/project
   a1b2c3d..f5e4d3c  main -> main

Authentication

Dits supports multiple authentication methods:

SSH Keys

# Use SSH URL
$ dits remote add origin git@example.com:team/project.git

# SSH key is used automatically from ~/.ssh/

Access Tokens

# Set credential helper
$ dits config --global credential.helper store

# Or use token in URL (not recommended for shared configs)
$ dits remote set-url origin https://token@example.com/project

Interactive Login

$ dits push
Username for 'https://example.com': jane
Password for 'https://jane@example.com': ****
Pushing to origin...

Bandwidth Management

Control upload and download speeds:

# Limit upload speed
$ dits config --global transfer.uploadLimit 50M

# Limit download speed
$ dits config --global transfer.downloadLimit 100M

# Set concurrent transfer streams
$ dits config --global transfer.parallel 4

Related Commands

Repository Commands - Clone and init
Branch Commands - Work with branches
Configuration - Configure remote settings