available on npm

Distributed file sync · CLI tool

Pull only what
you need.

Track and sync specific files or directories from remote Git repositories into local destinations. Manifest-driven. No full clones.

$ npm install -g @madkoo/dfiles Copied!
Get started View on GitHub
Scroll

Why dfiles

The file syncer for
developers who hate noise.

Cloning entire repos just to copy one config file is wasteful and hard to maintain. dfiles gives you precise, reproducible control over exactly what goes where.

📌

Manifest-driven

A single dfiles.json file tracks everything. Commit it, share it, reproduce it anywhere.

⚡

Shallow clones

First sync uses --depth 1. Subsequent pulls use git fetch. Minimal bandwidth, maximum speed.

🔒

Private repos

Inherits your existing Git auth — SSH keys, credential manager, anything already configured works automatically.

🗂️

Files & dirs

Sync individual files or entire directories. SHA-256 hashing means unchanged content is never recopied.

🌿

Branch-aware

Pin each entry to any branch. Mix sources from different branches across different repos freely.

🔍

Offline status

Check sync state without hitting the network. Know instantly what's current, outdated, or missing.

Quickstart

Up and running
in four commands.

1

Initialize a manifest

Creates a dfiles.json in the current directory (or any path you pass). This is your source of truth.

2

Add tracked entries

Point to any file or folder in any public or private repo. Give it an ID for easy targeting later.

3

Pull from remotes

Fetches only what changed. Use --dry-run to preview, or pass specific IDs to target a subset.

4

Check sync state

No network needed. Compare local files against cached state to see what's drifted.

bash
$ dfiles init ✓ created dfiles.json   $ dfiles add \ https://github.com/org/repo \ skills/canvas-design/SKILL.md \ ~/.claude/skills/canvas-design/SKILL.md \ --id canvas-skill ✓ added canvas-skill   $ dfiles pull ✓ canvas-skill → synced   $ dfiles status canvas-skill current

Reference

Commands

All the tools you need, none you don't.

Command Description Options
dfiles init [dir] Create a dfiles.json manifest in the target directory. dir (optional)
dfiles add <repo> <src> <dest> Track a file or directory from a remote repository. --branch <branch>
--id <id>
dfiles pull [ids...] Fetch updates from remotes and sync tracked entries. ids... (optional)
--dry-run
dfiles status Offline check — reports current, outdated, or missing. —
dfiles list List all tracked entries in the manifest. --json
dfiles remove <id> Remove a tracked entry from the manifest by ID. id (required)

Under the hood

How it works

Cache

SHA-256 keyed repos

Each repository is cached under ~/.dfiles/cache/<hash>/ keyed by a hash of its URL.

Clone

Shallow first

First-time setup uses git clone --depth 1. Only the latest snapshot — no full history.

Update

Incremental fetch

Subsequent syncs run git fetch + pull on the cached clone. Fast and minimal.

Diff

Hash-based sync

Files are compared with SHA-256. Identical content is never recopied, even across directories.

The manifest

dfiles.json

{
  "version": 1,
  "entries": [
    {
      "id": "canvas-design-skill",
      "repo": "https://github.com/org/repo",
      "branch": "main",
      "source": "skills/canvas-design/SKILL.md",
      "destination": "~/.claude/skills/canvas-design"
    },
    {
      "id": "deploy-workflow",
      "repo": "https://github.com/org2/repo2",
      "branch": "feature-branch",
      "source": "workflows/deploy.yml",
      "destination": "~/.local/workflows/deploy.yml"
    }
  ]
}
🆔
Stable IDs

id is how you target specific entries with pull or remove. Make them meaningful.

📁
Relative source paths

source is a path inside the remote repository. Files or directories both work.

🏠
Home-relative destinations

destination supports ~ expansion. The manifest is discovered by walking up parent directories, like Git finds .git.

🌿
Per-entry branches

Each entry can track a different branch. Mix main, release tags, or feature branches freely.