How do I sync changes between the main branch and the notes branch?

Use the included sync-notes.sh script to automatically move new files to the worktree, create missing symlinks, and update exclusion patterns.

Does this work for team members who don't have this Claude skill?

Yes, once initialized, the structure uses standard Git and symlink behavior. Team members can manually set up the worktree or run the provided shell scripts.

How does the symlink system work in this skill?

The skill creates relative symlinks in your main branch that point to the actual Markdown files stored in a separate directory mounted from another Git branch using git worktree.

Can I use this with existing documentation files?

Yes, the initialization script includes a --move-files flag that automatically migrates existing .md files to the worktree and replaces them with symlinks.

Will using symlinks affect my project's build process?

No, symlinks behave like regular files for most modern editors and build tools, but the underlying Git commits are isolated to the documentation branch.

Notes Worktree Documentation Manager

Name: Notes Worktree Documentation Manager
Author: hbbayrak

byhbbayrak

0•

Content Management

Manages project documentation in a separate Git worktree via symlinks to keep the main branch history clean and focused on code.

The Notes Worktree pattern provides a sophisticated documentation management system that isolates Markdown files within a dedicated orphan branch mounted as a Git worktree. By maintaining relative symlinks in the main project directory, developers can access and edit documentation in its logical context while ensuring that documentation commits do not clutter the primary code repository's history or pull requests. This skill is ideal for large projects where documentation changes frequently or is managed by separate teams, offering automated synchronization, VSCode integration, and a comprehensive suite of CLI tools for maintenance and deployment.

Key Features

01Automatic symlink generation for seamless contextual access to documentation across the project

020 GitHub stars

03Automated synchronization scripts for forward and reverse updates between code and notes

04Dual exclusion strategies supporting both shared .gitignore and local-only .git/info/exclude configurations

05Integrated VSCode support to automatically hide worktree directories and reduce workspace noise

06Isolated Git branch storage for Markdown files to maintain a clean primary commit history

Use Cases

01Reducing pull request noise by separating heavy documentation updates from functional code changes

02Managing project-wide README files across multiple subdirectories without cluttering the main branch

03Enabling documentation-only contributors to work in a dedicated branch without risking source code stability

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add hbbayrak/notes-worktree notes-worktree

For use in Claude.ai and ChatGPT

Download Skill