Basic Usage

Add templates to your .gitignore:

ign Python Node

Update existing templates:

ign

Sync specific templates with version pinning:

ign Python@main Node@abc1234

Command Line Options

ign [OPTIONS] [TEMPLATE[@HASH]...]

Options:

-f, --file FILE

Input .gitignore file (default: .gitignore, - for stdin)

-o, --output FILE

Output file (default: same as input, - for stdout)

-d, --diff

Show unified diff of changes

-n, --dry-run

Preview changes without writing

-v, --verbose

Verbose output: enable debug logging

-q, --quiet

Quiet output: only show errors and warnings

--logging TYPE

Logging format: console or json (default: console if TTY, otherwise JSON)

--debug

All-debug output: enable debug logging on all libraries

--version

Show version and exit

Arguments:

TEMPLATE[@HASH] GitHub template names (without .gitignore extension)

Optional @HASH pins to specific commit

Template Markers

ign uses special marker comments to track template sections:

# --- BEGIN https://raw.githubusercontent.com/github/gitignore/{SHA}/{TEMPLATE}.gitignore ---
# Template content here
# --- END https://raw.githubusercontent.com/github/gitignore/{SHA}/{TEMPLATE}.gitignore ---

These markers allow ign to:

• Identify which templates are already included

• Track the version (SHA) of each template

• Preserve local modifications between updates

Merge Strategy

When updating templates, ign uses a sophisticated merge algorithm:

1. Fetch versions: Downloads both old (current) and new (latest) template versions

2. Apply strategies: Tries two different merge approaches:

   • Strategy A: Apply (new - old) changes to your local modifications

   • Strategy B: Apply (local - old) changes to the new template

3. Conflict resolution: Falls back gracefully when automatic merging fails

4. Preserve customizations: Your local additions are always preserved

Local Modifications

You can safely add custom rules within template sections. For example:

# --- BEGIN https://raw.githubusercontent.com/github/gitignore/.../Python.gitignore ---
# Original Python template content...

# Your custom additions
*.local
/my-project-specific-file

# --- END https://raw.githubusercontent.com/github/gitignore/.../Python.gitignore ---

These modifications will be preserved during template updates.

Environment Variables

GITHUB_API_TOKEN

Optional GitHub API token for higher rate limits. Useful for heavy usage or when working with private repositories.

Example .env file:

GITHUB_API_TOKEN=ghp_your_token_here

Template Sources

Templates are fetched from the official GitHub gitignore repository. Available templates include:

• Languages: Python, Java, JavaScript, Go, Rust, C++, etc.

• Frameworks: Node, Django, Rails, Laravel, etc.

• Tools: JetBrains, VisualStudio, Vim, macOS, Windows, etc.

• Platforms: Android, iOS, Unity, etc.

For a complete list, visit: https://github.com/github/gitignore

Common Issues

Template not found

Ensure the template name matches exactly (case-sensitive) with files in the GitHub repository. Check https://github.com/github/gitignore for available templates.

Merge conflicts

If automatic merging fails, ign will preserve your current content and log the issue. You may need to manually resolve conflicts.

API rate limits

Set GITHUB_API_TOKEN environment variable to increase rate limits.

Missing END marker

If you manually edit marker comments, ensure BEGIN/END pairs match exactly. Use --debug for detailed error information.

Debug Mode

Enable debug logging for detailed information:

ign --debug --verbose Python

This shows:

• Template fetching details

• Merge strategy decisions

• Diff application results

• API request information