mdvdb tree

Show a file tree of all markdown files with sync status indicators. Each file is classified by comparing the files on disk against the index: Indexed (synced, hash matches), Modified (hash changed since last ingest), New (on disk but not in the index), or Deleted (in the index but no longer on disk).

Usage

mdvdb tree [OPTIONS]

Options

Option Details

--path <PREFIX>

Filters the tree to show only files and directories under the given path prefix. The prefix matches against the relative file paths in the tree.

When --path is used, the tree is rooted at the matching subtree. If no files match the prefix, an empty tree is displayed with zero counts.

# Show tree for docs directory only
mdvdb tree --path docs

# Show tree for a nested directory
mdvdb tree --path src/components

--shard <ID>

Resolves a configured Shard to its recursive folder scope and returns the same tree contract, rooted at that folder. Shards use the shared collection index; this option does not open a separate index. --shard conflicts with --path.

mdvdb tree --shard research
mdvdb tree --shard research --json

Global Options

These options apply to all commands. See Commands Index for details.

Sync Status Indicators

Each file in the tree is classified into one of four sync states by comparing the file on disk with what is stored in the index:

How Sync State Is Determined

1. Discover all markdown files on disk using the file scanner (respecting .gitignore, .mdvdbignore, and MDVDB_IGNORE_PATTERNS)
2. Compare each discovered file against the index:
   • If the file’s relative path exists in the index, read the file and compute its SHA-256 content hash
   • If the hash matches the stored hash, the file is Indexed
   • If the hash differs, the file is Modified
   • If the path is not in the index, the file is New
3. Check for deleted files: any path in the index that is not found on disk is marked Deleted

Human-Readable Output

When run without --json, tree displays an ASCII tree with box-drawing characters and colored status indicators:

.
├── docs
│   ├── api
│   │   ├── authentication.md
│   │   └── endpoints.md [modified]
│   ├── getting-started.md
│   └── overview.md [new]
├── blog
│   ├── 2024-01-15-intro.md
│   └── 2024-03-22-update.md
├── notes
│   └── meeting-notes.md [new]
└── README.md

12 files (8 indexed, 1 modified, 2 new, 1 deleted)

Output Elements

Color Coding

When colors are enabled (default), the tree uses ANSI colors:

Colors can be disabled with --no-color or by setting the NO_COLOR environment variable.

Sorting

Children at each directory level are sorted with:

1. Directories first (alphabetical)
2. Files second (alphabetical)

Examples

# Show full file tree
mdvdb tree

# Show tree as JSON
mdvdb tree --json

# Show tree for a specific directory
mdvdb tree --path docs

# Show tree for a specific project
mdvdb tree --root /path/to/project

# Show tree without colors
mdvdb tree --no-color

# Show tree scoped to a directory as JSON
mdvdb tree --path blog --json

# Show the recursive folder represented by a named Shard
mdvdb tree --shard research

JSON Output

FileTree (--json)

{
  "root": {
    "name": ".",
    "path": ".",
    "is_dir": true,
    "state": null,
    "children": [
      {
        "name": "docs",
        "path": "docs",
        "is_dir": true,
        "state": null,
        "children": [
          {
            "name": "api",
            "path": "docs/api",
            "is_dir": true,
            "state": null,
            "children": [
              {
                "name": "authentication.md",
                "path": "docs/api/authentication.md",
                "is_dir": false,
                "state": "indexed",
                "children": []
              },
              {
                "name": "endpoints.md",
                "path": "docs/api/endpoints.md",
                "is_dir": false,
                "state": "modified",
                "children": []
              }
            ]
          },
          {
            "name": "overview.md",
            "path": "docs/overview.md",
            "is_dir": false,
            "state": "new",
            "children": []
          }
        ]
      },
      {
        "name": "README.md",
        "path": "README.md",
        "is_dir": false,
        "state": "indexed",
        "children": []
      }
    ]
  },
  "total_files": 12,
  "indexed_count": 8,
  "modified_count": 1,
  "new_count": 2,
  "deleted_count": 1
}

FileTree Fields

FileTreeNode Fields

FileState Values

Filtered Tree (--path)

When --path is used, the JSON output has the same structure but rooted at the matching subtree. If no files match the prefix, an empty tree is returned:

{
  "root": {
    "name": ".",
    "path": ".",
    "is_dir": true,
    "state": null,
    "children": []
  },
  "total_files": 0,
  "indexed_count": 0,
  "modified_count": 0,
  "new_count": 0,
  "deleted_count": 0
}

Notes

• The tree command never modifies the index. If no usable index exists, it still returns a discovery-only tree and marks every on-disk document new; if an existing index cannot be opened, it warns and degrades to that filesystem view.
• File discovery respects .gitignore, .mdvdbignore, and MDVDB_IGNORE_PATTERNS — excluded files do not appear in the tree.
• Summary counts in --path and --shard mode are recomputed from the visible subtree.
• Deleted files appear in the tree even though they no longer exist on disk. They will be removed from the index on the next mdvdb ingest.
• The content hash comparison reads files from disk, so the tree command may be slightly slower than status for large projects.

Related Commands

• mdvdb ingest — Index new and modified files, remove deleted files
• mdvdb status — Quick summary of index counts without the tree structure
• mdvdb schema — View inferred metadata schema from indexed files
• mdvdb get — View detailed metadata for a specific file

See Also

• Index Storage — How the index tracks file hashes and content
• Ignore Files — How .gitignore, .mdvdbignore, and MDVDB_IGNORE_PATTERNS control file discovery
• Configuration — Environment variables and config options
• JSON Output Reference — Complete JSON schema reference