ST007: HasGitignore

Overview

Property Value
ID ST007
Name HasGitignore
Group structure
Severity NOTE

Description

Checks that a .gitignore file exists in the package root directory.

A .gitignore file is essential for any project using Git version control, as it prevents unwanted files from being tracked and committed.

What it checks

The check verifies that .gitignore exists in the package root directory.

Why it matters

Without a proper .gitignore, you risk committing:

  • Build artifacts - dist/, build/, *.egg-info/
  • Cache files - __pycache__/, .pytest_cache/, .mypy_cache/
  • Virtual environments - .venv/, venv/, .env/
  • IDE settings - .idea/, .vscode/
  • Sensitive data - .env files, credentials, API keys
  • Large files - Compiled binaries, data files

This leads to:

  • Repository bloat
  • Merge conflicts
  • Security vulnerabilities
  • Confused collaborators

How to fix

Create a .gitignore file in your package root. Here’s a comprehensive template for Python projects:

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/

# Translations
*.mo
*.pot

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

# IDE
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

Using gitignore.io

You can generate a customized .gitignore using gitignore.io:

curl -sL https://www.toptal.com/developers/gitignore/api/python,venv,pycharm,vscode > .gitignore

Using GitHub templates

When creating a new repository on GitHub, select “Python” from the .gitignore template dropdown to get a pre-configured file.

Configuration

Skip this check

[tool.pycmdcheck]
skip = ["ST007"]

CLI

pycmdcheck --skip ST007