Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt

Use this file to discover all available pages before exploring further.

v0.5.0-rc.2 adds the trellis uninstall command (#221) and patches Windows compatibility (#218) and Copilot custom-agent frontmatter (PR #210). No new migrations.

​
Enhancements

​
trellis uninstall command (#221)

Removes all files generated by trellis along with the .trellis/ directory. The deletion list is sourced from .trellis/.template-hashes.json; files not listed in the manifest are not touched. 
trellis uninstall              # default: list + Continue? [Y/n]
trellis uninstall --yes        # skip prompt
trellis uninstall --dry-run    # list then exit, no changes
Pre-checks:
ConditionBehavior
.trellis/ directory missingFriendly exit 0 with "Trellis is not installed in this project"
.trellis/ exists but .template-hashes.json missingExit 1 with hint to delete .trellis/ manually
Both presentProceed to scan + listing
Output is split into two columns:
  • Will be deleted — opaque files (.py / .md / .ts) plus structured-config files that scrub down to nothing, plus the .trellis/ directory itself.
  • Will be modified — structured-config files where trellis-owned entries are stripped but user-added fields are preserved.
Four scrubbers cover 11 structured config files:
ScrubberFiles
scrubHooksJson (nested).claude/settings.json, .gemini/settings.json, .factory/settings.json, .codebuddy/settings.json, .qoder/settings.json, .codex/hooks.json
scrubHooksJson (flat).cursor/hooks.json, .github/copilot/hooks.json
scrubOpencodePackageJson.opencode/package.json — removes dependencies["@opencode-ai/plugin"]
scrubPiSettings.pi/settings.json — strips trellis entries from extensions / skills / prompts arrays; removes enableSkillCommands
scrubCodexConfigToml.codex/config.toml — removes project_doc_fallback_filenames and the trellis NOTE comment block
Command matching rule: only the last whitespace token of a command string (the script path) is used for comparison. Substring occurrences elsewhere (e.g. inside an echo) do not match. Execution order: scrubber → unlink → cleanupEmptyDirs (prunes emptied subdirectories) → managed-root sweep (prunes empty .claude/ / .cursor/ / etc. top-level dirs) → rm -rf .trellis/. Directories that still contain user files are preserved. Manifest-listed paths are removed unconditionally; no hash check is performed. User-modified trellis files are deleted as well. 23 new tests (15 scrubber unit + 8 integration); 830 tests pass overall.

​
Bug Fixes

​
Windows python3 → python at write time (#218, PR #220)

Windows has no python3 executable. replacePythonCommandLiterals() runs at init/update write time on process.platform === "win32": 
content
  .split('\n')
  .map((line) => (line.startsWith('#!') ? line : line.replaceAll('python3', 'python')))
  .join('\n');
  • Write-time only — template source files keep python3; replacement happens at file generation time.
  • Shebang preserved — lines beginning with #! are not replaced.
  • Idempotent — python does not contain python3; running multiple times produces the same result.
  • Coverage — configurators/{claude,codex,copilot,opencode,pi}.ts, configurators/shared.ts (writeSkills / writeAgents / writeSharedHooks / resolvePlaceholders / buildPullBasedPrelude), configurators/workflow.ts, templates/extract.ts, configurators/index.ts (collectPlatformTemplates), commands/update.ts (collectTemplateFiles). init and update produce byte-for-byte identical output on Windows.
9 new platform-mocked unit tests in test/configurators/shared.test.ts cover win32/linux/darwin behavior, shebang preservation, multiline content, idempotency, and the documented python3x substring boundary.

​
Copilot custom agent tools frontmatter (PR #210)

injectPullBasedPreludeMarkdown() now uses a regex frontmatter splitter (splitMarkdownFrontmatter) instead of line-based scanning, handling CRLF endings cleanly. mapLegacyToolToCopilot() translates Claude-style tool tokens (Read, Write, Edit, Glob, …) into Copilot’s lowercase shape (read, edit, …) so custom agents authored against the Claude convention render correctly under Copilot. Regression coverage added in test/regression.test.ts.

​
Upgrade

npm install -g @mindfoldhq/trellis@rc
trellis update
Projects on 0.5 (beta or earlier rc) run trellis update. Projects upgrading from 0.4.x run trellis update --migrate because the 0.5 migration chain begins at 0.5.0-beta.0. rc.2 adds no new migration entries.