{"id":3273,"library":"setuptools-git","title":"Setuptools Git Plugin","description":"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.","status":"maintenance","version":"1.2","language":"en","source_language":"en","source_url":"https://github.com/msabramo/setuptools-git","tags":["setuptools","git","packaging","build-system","plugin"],"install":[{"cmd":"pip install setuptools-git","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"This is a plugin for setuptools and requires it to function.","package":"setuptools","optional":false},{"reason":"Relies on the Git command-line tool and repository metadata (.git directory) to determine tracked files.","package":"git (executable)","optional":false}],"imports":[{"note":"setuptools-git is a plugin that modifies setuptools behavior; no direct import of setuptools_git is typically needed in user code.","symbol":"setup","correct":"from setuptools import setup"},{"note":"Used in conjunction with setup() to automatically discover packages.","symbol":"find_packages","correct":"from setuptools import find_packages"}],"quickstart":{"code":"import os\nimport subprocess\nfrom setuptools import setup, find_packages\n\n# Create a dummy git repo for demonstration\nif not os.path.exists('.git'):\n    print(\"Initializing git repository...\")\n    subprocess.run(['git', 'init', '-b', 'main'], check=True)\n    with open('README.md', 'w') as f: f.write('# My Project')\n    os.makedirs('my_package', exist_ok=True)\n    with open('my_package/__init__.py', 'w') as f: f.write('__version__ = \"0.1.0\"')\n    with open('my_package/module.py', 'w') as f: f.write('def hello(): return \"Hello\"')\n    with open('my_package/data.txt', 'w') as f: f.write('some data')\n    with open('.gitignore', 'w') as f: f.write('*.tmp')\n    with open('ignored.tmp', 'w') as f: f.write('temp file')\n    subprocess.run(['git', 'add', '.'], check=True)\n    subprocess.run(['git', 'commit', '-m', 'Initial commit'], check=True)\n\n\nsetup(\n    name='my-project',\n    version='0.1.0',\n    packages=find_packages(),\n    include_package_data=True, # This activates setuptools-git functionality\n    setup_requires=[\"setuptools-git >= 0.3\"],\n    # Minimal metadata for a runnable setup.py\n    author='Your Name',\n    author_email='your.email@example.com',\n    description='A short description',\n    long_description='A longer description.',\n    url='http://example.com/your-project',\n    python_requires='>=3.6',\n    install_requires=[]\n)\n\nprint(\"\\n--- To build the source distribution (sdist): ---\")\nprint(\"python setup.py sdist\")\nprint(\"This will include git-tracked files like my_package/module.py and my_package/data.txt, but exclude ignored.tmp.\")\n\n# Clean up dummy repo (optional)\n# import shutil\n# if os.path.exists('.git'):\n#     shutil.rmtree('.git')\n# if os.path.exists('my_package'):\n#     shutil.rmtree('my_package')\n# if os.path.exists('README.md'):\n#     os.remove('README.md')\n# if os.path.exists('.gitignore'):\n#     os.remove('.gitignore')\n# if os.path.exists('ignored.tmp'):\n#     os.remove('ignored.tmp')","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"deprecated","affected_versions":"<=1.2 (used with setuptools >= 69)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}