Environment Variables

Environment variables provide a way to configure Dits without modifying configuration files, useful for scripts and CI/CD pipelines.

Priority Order

Environment variables override configuration file settings. The full priority order is: Environment → Repository → Global → System → Defaults

Core Environment Variables

Variable	Description	Example
DITS_DIR	Override .dits directory location	/path/to/.dits
DITS_WORK_TREE	Override working tree location	/path/to/worktree
DITS_CACHE_DIR	Override cache directory	/path/to/cache
DITS_CONFIG_GLOBAL	Override global config file path	~/.config/dits/config
DITS_CONFIG_SYSTEM	Override system config file path	/etc/ditsconfig
DITS_EDITOR	Override editor for messages	vim
DITS_PAGER	Override pager for output	less -R
DITS_SSH_COMMAND	Custom SSH command	ssh -i ~/.ssh/custom_key
DITS_AUTHOR_NAME	Override author name	Script Bot
DITS_AUTHOR_EMAIL	Override author email	bot@example.com
DITS_AUTHOR_DATE	Override author date	2024-01-15T10:30:00
DITS_COMMITTER_NAME	Override committer name	CI Server
DITS_COMMITTER_EMAIL	Override committer email	ci@example.com
DITS_COMMITTER_DATE	Override committer date	2024-01-15T10:30:00

Repository Location Variables

DITS_DIR

Override the location of the .dits directory:

# Use a different .dits location
$ DITS_DIR=/custom/path/.dits dits status

# Useful for working with multiple repositories
$ DITS_DIR=/repo1/.dits dits log
$ DITS_DIR=/repo2/.dits dits log

DITS_WORK_TREE

Set the working tree location independently from the repository:

# Work tree in different location
$ DITS_DIR=/repo/.dits DITS_WORK_TREE=/worktree dits status

# Useful for bare repositories with worktrees
$ export DITS_DIR=/srv/repo.dits
$ export DITS_WORK_TREE=/var/www/site
$ dits pull

DITS_CACHE_DIR

Override where Dits stores cached chunks:

# Use faster storage for cache
$ export DITS_CACHE_DIR=/ssd/dits-cache

# Shared cache for CI runners
$ export DITS_CACHE_DIR=/shared/cache/dits

Author/Committer Override

Override the author and committer information for commits:

# In a CI pipeline, commit as the CI system
$ export DITS_AUTHOR_NAME="CI Bot"
$ export DITS_AUTHOR_EMAIL="ci@example.com"
$ export DITS_COMMITTER_NAME="CI Bot"
$ export DITS_COMMITTER_EMAIL="ci@example.com"
$ dits commit -m "Automated commit"

# Backdate a commit (for importing history)
$ DITS_AUTHOR_DATE="2023-06-15T14:30:00" dits commit -m "Import"

Editor and Pager

# Use a specific editor for this session
$ DITS_EDITOR="nano" dits commit

# Disable pager
$ DITS_PAGER="" dits log

# Use a custom pager
$ DITS_PAGER="less -FRSX" dits diff

SSH Configuration

# Use a specific SSH key
$ DITS_SSH_COMMAND="ssh -i ~/.ssh/deploy_key" dits clone git@example.com:repo

# Use SSH with custom options
$ export DITS_SSH_COMMAND="ssh -o StrictHostKeyChecking=no"
$ dits push

Debug and Trace Variables

Variable	Description	Values
DITS_TRACE	Enable trace logging	0, 1, 2 (verbosity level)
DITS_TRACE_PACKET	Trace network packets	0 or 1
DITS_TRACE_PERFORMANCE	Trace performance metrics	0 or 1
DITS_CURL_VERBOSE	Verbose HTTP output	0 or 1

Debugging Commands

# Enable trace logging
$ DITS_TRACE=1 dits fetch
trace: fetch origin
trace: connecting to example.com
trace: negotiating pack...

# More verbose tracing
$ DITS_TRACE=2 dits push

# Trace network packets
$ DITS_TRACE_PACKET=1 dits clone https://example.com/repo

# Performance tracing
$ DITS_TRACE_PERFORMANCE=1 dits add large-file.mov
performance: chunking: 2.345s
performance: hashing: 0.567s
performance: staging: 0.123s

CI/CD Examples

GitHub Actions

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DITS_AUTHOR_NAME: "GitHub Actions"
      DITS_AUTHOR_EMAIL: "actions@github.com"
      DITS_CACHE_DIR: /tmp/dits-cache
    steps:
      - uses: actions/checkout@v4
      - name: Configure Dits
        run: |
          dits config user.name "$DITS_AUTHOR_NAME"
          dits config user.email "$DITS_AUTHOR_EMAIL"
      - name: Deploy
        run: |
          dits add .
          dits commit -m "Deploy from CI"
          dits push

GitLab CI

# .gitlab-ci.yml
variables:
  DITS_AUTHOR_NAME: "GitLab CI"
  DITS_AUTHOR_EMAIL: "ci@gitlab.com"
  DITS_SSH_COMMAND: "ssh -o StrictHostKeyChecking=no"

deploy:
  script:
    - dits push

Jenkins

// Jenkinsfile
pipeline {
    environment {
        DITS_AUTHOR_NAME = 'Jenkins'
        DITS_AUTHOR_EMAIL = 'jenkins@example.com'
    }
    stages {
        stage('Build') {
            steps {
                sh 'dits pull'
                sh 'make build'
            }
        }
    }
}

Shell Configuration

Add environment variables to your shell profile:

# ~/.bashrc or ~/.zshrc

# Dits configuration
export DITS_EDITOR="code --wait"
export DITS_PAGER="less -R"

# Shared cache
export DITS_CACHE_DIR="$HOME/.cache/dits"

# Debug mode (uncomment when needed)
# export DITS_TRACE=1

Checking Active Configuration

# See effective configuration including env vars
$ dits config --show-origin --list

# Check specific value source
$ dits config --show-origin user.email
file:~/.ditsconfig    user.email=jane@example.com

# With environment override
$ DITS_AUTHOR_EMAIL="override@example.com" dits config --show-origin user.email
command line: user.email=override@example.com