Setuptools Git Plugin

1.2 · maintenance · verified Sat Apr 11

setuptools-git is a plugin for setuptools that enables integration with Git. It allows setuptools to automatically include all files tracked by Git in a package distribution, serving as an alternative to explicitly listing files in MANIFEST.in. The current version is 1.2, last released in February 2017, and it was formerly known as gitlsfiles.

Warnings

gotcha setuptools-git requires a local Git repository with its metadata (.git directory) to be present during package distribution. It will not work if building from a non-git source distribution (e.g., a tarball without .git) or if the plugin is not installed in the build environment.
Fix: Ensure `setuptools-git` is in `setup_requires` and always build from a Git checkout. Add warnings to your project's documentation if building from non-git distributions is a concern.
deprecated The latest release of setuptools-git (1.2) is from February 2017. Modern Python packaging often uses `pyproject.toml` and build backends like `setuptools-scm` for versioning or relies on more explicit `MANIFEST.in` configurations. Compatibility with very recent `setuptools` versions (e.g., 69+ which have introduced breaking changes around `setup.cfg` parsing, `setup.py develop` removal, and internal reorganizations) is not guaranteed and may lead to unexpected build failures.
Fix: For new projects or if encountering build issues, consider using `MANIFEST.in` directly, or explore more actively maintained tools like `setuptools-scm` if your primary goal is versioning based on Git. If you must use `setuptools-git`, pin an older, compatible version of `setuptools` in your `pyproject.toml`'s `build-system.requires` (e.g., `setuptools<69`).
gotcha This package is for including *git-tracked files* in your distribution, not for *versioning* your package based on Git tags/commits. Users often confuse it with other tools like `setuptools-scm` or `setuptools-git-versioning`, which specifically handle automatic version generation from Git.
Fix: Clarify your requirements: if you need automated versioning from Git, use `setuptools-scm` (recommended) or `setuptools-git-versioning`. If you only need to include Git-tracked files in your sdist/wheel, `setuptools-git` is applicable, but consider its age and potential compatibility issues with newer `setuptools` versions.

Install

pip install setuptools-git Install via pip

Imports

setup
```
from setuptools import setup
```
setuptools-git is a plugin that modifies setuptools behavior; no direct import of setuptools_git is typically needed in user code.
find_packages
```
from setuptools import find_packages
```
Used in conjunction with setup() to automatically discover packages.

Quickstart

To use setuptools-git, ensure it is listed in `setup_requires` in your `setup.py` and set `include_package_data=True` in your `setup()` call. It requires an initialized Git repository with committed files. This example creates a minimal `setup.py` and a dummy Git repository to demonstrate how tracked files (like `my_package/module.py` and `my_package/data.txt`) are included, while ignored files (`ignored.tmp`) are not, when building a source distribution.

import os
import subprocess
from setuptools import setup, find_packages

# Create a dummy git repo for demonstration
if not os.path.exists('.git'):
    print("Initializing git repository...")
    subprocess.run(['git', 'init', '-b', 'main'], check=True)
    with open('README.md', 'w') as f: f.write('# My Project')
    os.makedirs('my_package', exist_ok=True)
    with open('my_package/__init__.py', 'w') as f: f.write('__version__ = "0.1.0"')
    with open('my_package/module.py', 'w') as f: f.write('def hello(): return "Hello"')
    with open('my_package/data.txt', 'w') as f: f.write('some data')
    with open('.gitignore', 'w') as f: f.write('*.tmp')
    with open('ignored.tmp', 'w') as f: f.write('temp file')
    subprocess.run(['git', 'add', '.'], check=True)
    subprocess.run(['git', 'commit', '-m', 'Initial commit'], check=True)


setup(
    name='my-project',
    version='0.1.0',
    packages=find_packages(),
    include_package_data=True, # This activates setuptools-git functionality
    setup_requires=["setuptools-git >= 0.3"],
    # Minimal metadata for a runnable setup.py
    author='Your Name',
    author_email='your.email@example.com',
    description='A short description',
    long_description='A longer description.',
    url='http://example.com/your-project',
    python_requires='>=3.6',
    install_requires=[]
)

print("\n--- To build the source distribution (sdist): ---")
print("python setup.py sdist")
print("This will include git-tracked files like my_package/module.py and my_package/data.txt, but exclude ignored.tmp.")

# Clean up dummy repo (optional)
# import shutil
# if os.path.exists('.git'):
#     shutil.rmtree('.git')
# if os.path.exists('my_package'):
#     shutil.rmtree('my_package')
# if os.path.exists('README.md'):
#     os.remove('README.md')
# if os.path.exists('.gitignore'):
#     os.remove('.gitignore')
# if os.path.exists('ignored.tmp'):
#     os.remove('ignored.tmp')

view raw JSON →