layer

Product Introduction

1. Definition: layer (also known as git-layer) is a specialized command-line interface (CLI) tool written in Rust, designed for advanced local file management within Git repositories. It functions as a local-first overlay for Git, specifically targeting the management of untracked files without modifying the project's shared version-controlled configuration.

2. Core Value Proposition: layer enables developers to maintain a private workspace by managing the .git/info/exclude file. This prevents "gitignore pollution" where personal notes, AI context files, and scratch documents are forced into a team's shared .gitignore. By utilizing the built-in git/info/exclude mechanism, layer keeps local files invisible to git status while ensuring they remain accessible on disk and hidden from global repository history.

Main Features

1. Automated .git/info/exclude Orchestration: Unlike .gitignore, which is tracked and shared across all clones of a repository, layer manages .git/info/exclude, a local-only file that Git respects but never commits. The tool provides commands like layer scan to automatically detect common AI-related context files (e.g., from Cursor, Claude Code, or Windsurf) and instantly adds them to the local exclusion list.

2. Visibility Toggling (On/Off States): layer provides a unique mechanism to temporarily un-hide and re-hide files using layer off and layer on. This is critical for modern AI-assisted development workflows where tools like Claude Code or Codex need to "see" a file to process context, but the developer wants the file hidden from the git status output and file pickers during standard coding and committing phases.

3. Private Shadow History and Snapshotting: Because Git ignores files listed in exclude, it does not track their changes, leading to a risk of data loss. layer solves this by maintaining a private shadow repository in a local .layer/ directory. Users can run layer snapshot to save the state of hidden files and use layer diff, layer log, or layer blame to inspect changes or revert to previous versions, effectively providing version control for ignored files.

4. Global Ignore Management: Beyond repository-specific rules, the tool includes layer global commands. This allows developers to manage Git’s global ignore file (typically defined in core.excludesFile) to apply persistent exclusion rules across every repository on their machine without manual configuration of global git configs.

Problems Solved

1. Repository Configuration Bloat: Teams often struggle with bloated .gitignore files filled with individual developer preferences, such as specific IDE configs or personal notes. layer moves these entries to a local-only layer, keeping the project’s root configuration clean and relevant only to the shared codebase.

2. Exposure of Sensitive AI Context: AI tools generate significant metadata (e.g., CLAUDE.md, architecture-notes.md). If these are accidentally committed, they can leak internal onboarding processes or prompts. layer ensures these remain local-only by default while allowing the developer to interact with them via their preferred LLM interface.

3. Target Audience: This tool is essential for Software Engineers using AI IDEs (Cursor, VS Code with Copilot, Windsurf), Open Source Contributors who need to keep local scratchpads in forks, and Technical Leads who want to enforce clean .gitignore standards across a large organization.

4. Use Cases: Hiding API specs and backend guides during a refactor; managing per-repository custom prompts for LLMs; maintaining local-only onboarding notes that aren't ready for team-wide distribution; and performing "surgical" commits where certain files need to be temporarily ignored to avoid cluttering a Pull Request.

Unique Advantages

1. Non-Invasive Integration: layer leverages standard Git hooks and features (.git/info/exclude) rather than creating a proprietary vendor-lock-in format. If a user stops using layer, the files remain ignored by Git as per standard protocols.

2. Local Versioning for Ignored Files: This is the tool's primary innovation. Traditional Git usage means once a file is ignored, its history is lost. layer provides a "safety net" via its snapshot system, allowing for TUI-based (Terminal User Interface) diffing and per-line blame for files that technically don't exist in the Git tree.

3. Workflow Efficiency: The interactive tree picker (layer add) and automated discovery (layer scan) significantly reduce the friction of manual path entry, making local file privacy a one-second task rather than a manual configuration chore.

Frequently Asked Questions (FAQ)

1. What is the difference between .gitignore and .git/info/exclude? .gitignore is a tracked file that is committed to the repository and shared with every developer who clones the project. .git/info/exclude is a local file within the .git folder that functions exactly like .gitignore but is never committed or shared. layer automates the management of the latter to keep your personal workflow private.

2. Do editors like Cursor and VS Code respect files managed by layer? Yes. Most modern editors and AI coding assistants respect Git’s ignore rules. When layer adds a file to .git/info/exclude, it will typically disappear from the editor's file explorer and autocomplete results. You can use layer off to make them reappear instantly when you need to edit them.

3. Is my "shadow history" shared with other developers? No. All snapshots and history logs created by layer are stored in a local .layer/ directory within your repository. This data is strictly local to your machine and is never pushed to remote servers or shared during a git push, ensuring complete privacy for your local notes and scratch docs.