Getting Started

distman reads deployment instructions from a dist.json file located at the root of a directory or Git repository. Each named target maps a source object to a destination.

Install

pip install -U distman

This installs three commands:

• distman: suite command with dist and cache subcommands
• dist: direct distribution and version-management command
• distcache: direct cache-management command

Create a Distribution File

{
  "author": "pipeline@example.com",
  "targets": {
    "bin": {
      "source": "bin/tool",
      "destination": "{DEPLOY_ROOT}/bin/tool"
    },
    "library": {
      "source": "lib/example",
      "destination": "{DEPLOY_ROOT}/lib/python/example"
    }
  }
}

Sources are relative to the directory containing dist.json. Destinations may contain {NAME} placeholders, which distman replaces from the current process environment and its built-in defaults.

Preview a Deployment

Always inspect a new configuration with a dry run first:

dist --dryrun --verbose

Deploy every configured target without interactive prompts:

dist --yes

Deploy selected targets:

dist --target bin library --yes
dist --target 'lib*' --yes

Version Layout

For a destination such as {DEPLOY_ROOT}/bin/tool, distman stores numbered objects under a sibling versions directory and makes the requested destination a symlink to the active object:

bin/
├── tool -> versions/tool.1.a1b2c3d
└── versions/
    └── tool.1.a1b2c3d

The suffix records a monotonically increasing version number and, for commit-based matching, a short Git commit. Metadata is written beside deployed targets, and successful mutations update .distman/epoch under the deployment root so local caches can detect changes.

Inspect and Roll Back

dist --show
dist --target bin --number 1
dist --target bin --commit a1b2c3d
dist --target bin --reset

Use at least four characters when selecting a commit. --reset points the selected target back to its latest version.

Git Safety

distman uses Git information to identify the source and version. A normal deployment stops when a selected source has uncommitted changes or the local repository is behind its upstream. Use --force only when that behavior is intentional.