Gitignore Templates - Usage and Contribution Guide

A practical guide for using GitHub's .gitignore templates in your projects and contributing new templates to the collection.

1. Prerequisites

• Git (version 2.0 or higher) installed and configured
• Text editor (VS Code, Vim, Nano, or similar) for viewing and editing templates
• GitHub account (required only if contributing templates)
• cURL or wget (optional, for downloading individual templates without cloning)

2. Installation

Clone the Repository (Full Collection)

git clone https://github.com/github/gitignore.git
cd gitignore

Download Individual Templates

Without cloning the entire repository:

# Download Python template to current project
curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore

# Download Node template
wget https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -O .gitignore

Template Locations

After cloning, templates are organized as:

• Root directory: Common programming languages and frameworks (Python.gitignore, Node.gitignore, etc.)
• Global/: Editor, tool, and OS-specific patterns (Vim.gitignore, macOS.gitignore, etc.)
• community/: Specialized and versioned templates

3. Configuration

Project-Specific Configuration

Copy the appropriate template to your repository root:

# From cloned repository
cp gitignore/Python.gitignore /path/to/your/project/.gitignore

# Or manually concatenate multiple templates
cat gitignore/Python.gitignore gitignore/Global/VisualStudioCode.gitignore > /path/to/your/project/.gitignore

Global Configuration (Recommended for Editor/OS Templates)

Configure Git to use a global excludes file for patterns that apply to all repositories:

# Create global gitignore using a template from the Global folder
cp gitignore/Global/macOS.gitignore ~/.gitignore_global

# Configure Git to use it
git config --global core.excludesfile ~/.gitignore_global

# Verify configuration
git config --global core.excludesfile

Combining Multiple Templates

For projects using multiple technologies, concatenate templates (order matters - specific before general):

# Example: Python project using VS Code on macOS
cat gitignore/Python.gitignore > .gitignore
echo "" >> .gitignore  # Add newline for safety
cat gitignore/Global/VisualStudioCode.gitignore >> .gitignore
echo "" >> .gitignore
cat gitignore/Global/macOS.gitignore >> .gitignore

4. Usage & Validation

Testing Ignore Patterns

Verify your .gitignore is working before committing:

# Check if a specific file is ignored
git check-ignore -v debug.log

# Check why a file is NOT ignored (debugging)
git check-ignore --no-index -v debug.log

# List all ignored files in repository
git ls-files --others --ignored --exclude-standard

Applying to Existing Repositories

If files were already tracked before adding .gitignore:

# Stop tracking files that are now in .gitignore
git rm --cached filename

# Stop tracking all files now listed in .gitignore
git rm -r --cached .
git add .
git commit -m "Apply .gitignore patterns and stop tracking ignored files"

Validating Template Syntax

Check for syntax errors in your .gitignore:

# Git will warn about invalid patterns during status checks
git status

# Test specific patterns
git check-ignore --verbose pattern_name

5. Contributing (Deployment of New Templates)

Fork and Branch Workflow

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/gitignore.git
cd gitignore
git checkout -b add-template-for-xyz

Creating New Templates

1. Root templates (mainstream technologies): Place directly in repository root

   • Filename format: TechnologyName.gitignore
   • Must be "evergreen" (current stable version, no version numbers in filename)

2. Community templates (specialized/versioned): Place in community/ directory

   • Versioned format: community/Framework/Framework-v1.gitignore
   • Current version can be community/Framework/Framework.gitignore

Template Requirements

# gitignore template for [Technology]
# website: [Official URL]
# 
# Recommended: [List any complementary templates to include]
# - Global/EditorName.gitignore

[Actual ignore patterns, one per line]
[Comments explaining non-obvious patterns]

Submit Changes

git add YourTemplate.gitignore
git commit -m "Add template for TechnologyName

- Covers build artifacts from v2.x and v3.x
- Excludes dependency directories
- Documentation: [link to official docs]"
git push origin add-template-for-xyz

Then open a Pull Request on GitHub with:

• Link to the technology's homepage
• Link to documentation supporting the ignored files
• Explanation of why these rules apply universally

6. Troubleshooting

Files Still Showing as Modified After Adding to .gitignore

Problem: Git continues tracking files that were committed before being added to .gitignore.

Solution:

git rm --cached <file>
# Or for directories
git rm -r --cached <directory>
git commit -m "Remove ignored files from tracking"

Global .gitignore Not Working

Problem: Patterns in global excludes file not being applied.

Solution:

# Verify the file is set
git config --global core.excludesfile

# If empty or wrong, reset it
git config --global core.excludesfile ~/.gitignore_global

# Ensure filename matches exactly (case-sensitive)

Pattern Not Matching

Problem: File should be ignored but isn't.

Solution:

# Check if pattern is correct
git check-ignore --verbose filename

# Common fixes:
# - Remove leading slash for directory-wide patterns
# - Ensure no trailing spaces in .gitignore lines
# - Check case sensitivity (Git is case-sensitive, filesystem may not be)

Combining Templates Creates Duplicates

Problem: Merged templates have overlapping patterns.

Solution:

# Remove duplicates while preserving order (keeps first occurrence)
awk '!seen[$0]++' combined.gitignore > .gitignore

Windows Line Endings Issues

Problem: .gitignore created on Windows causes issues on Unix systems.

Solution:

# Convert line endings to LF
dos2unix .gitignore

# Or configure Git to handle it automatically
git config --global core.autocrlf input