Skip to content
Pilum

Ignore Files

Pilum discovers services by walking the project for pilum.yaml files. Ignore patterns let you skip directories and services you don’t want deployed: examples, fixtures, archived services.

Where Patterns Come From

Pilum reads two files from the directory discovery starts in (the directory you run Pilum from, or the project root for pilum list and pilum compose):

  1. .gitignore — read by default. Pass --no-gitignore to skip it.
  2. .pilumignore — Pilum-specific additions.

Patterns from both files are combined. If neither file yields any pattern, Pilum falls back to ignoring node_modules, .git and vendor. The fallback is not added once either file has patterns, so list those directories yourself if your .gitignore doesn’t.

Only .gitignore and .pilumignore in the discovery root are read; files in subdirectories are not.

Basic Usage

.pilumignore
examples
test-*
archived/

Any directory or pilum.yaml matching these patterns is skipped. Ignored directories are not traversed.

Pattern Syntax

Pilum uses its own simple matcher, not full gitignore semantics. Patterns are matched against paths relative to the discovery root.

Names

A plain name matches any path component with that name, at any depth:

Terminal window
# Ignore any directory named "examples"
examples

This matches examples/, services/examples/ and deep/nested/examples/.

Rooted Paths

A pattern ending in / matches only that path from the root, and everything under it:

Terminal window
# Only the root examples/ directory
examples/


# A specific nested directory
services/legacy/

examples/ matches examples/ but not services/examples/.

Globs

*, ? and [...] work as in shell globs, within one path component:

Terminal window
# Directories starting with "test-"
test-*


# Directories ending with "-old"
*-old


# Directories starting with an underscore
_*

A glob containing / is matched against the full relative path, so services/old-* matches services/old-api only.

Comments and Blank Lines

Lines starting with # and blank lines are ignored.

Not Supported

  • Negation — lines starting with ! are skipped, so you can’t re-include something an earlier pattern excluded.
  • Leading / — /dist never matches. Use dist/ for a root-only match.
  • ** — matches like a single * within one component; it does not span directories.

Example .pilumignore

.pilumignore
# Development and testing
examples
fixtures
test-*
testdata


# Dependencies and build output
dist
node_modules
vendor


# Archived/deprecated services
archived/
*-deprecated
*-old


# Documentation
docs

Discovery Depth

Discovery also stops four levels below the root: a/b/c/d/pilum.yaml is found, a/b/c/d/e/pilum.yaml is not.

Debugging

pilum list shows what was discovered. To see what was skipped, run a dry run with --debug:

Terminal window
pilum dry-run --debug
[debug] Loaded 4 ignore patterns
[debug] Ignoring directory: archived
[debug] Ignoring directory: examples

The pattern count covers both files combined. pilum list has no --debug flag.

Common Patterns

Monorepo with Examples

my-project/
├── .pilumignore          # examples
├── services/
│   ├── api/
│   │   └── pilum.yaml    # ✓ discovered
│   └── worker/
│       └── pilum.yaml    # ✓ discovered
└── examples/
    └── demo-service/
        └── pilum.yaml    # ✗ ignored

Archived Services

.pilumignore
archived/
*-deprecated
my-project/
├── services/
│   ├── payments/
│   │   └── pilum.yaml    # ✓ discovered
│   └── payments-deprecated/
│       └── pilum.yaml    # ✗ ignored
└── archived/
    └── old-api/
        └── pilum.yaml    # ✗ ignored

Next Steps