setuptools-git 1.2

关于

这是一个为setuptools提供的插件，用于实现git集成。安装后，Setuptools可以包含所有由git跟踪的文件到包分布中。这是与< span class="docutils literal">MANIFEST.in中的显式包含规范不同的方法。

在这里，包分布指的是您使用setup.py创建的包，例如

$> python setup.py sdist
$> python setup.py bdist_rpm
$> python setup.py bdist_egg

这个包以前被称为gitlsfiles。名称更改是setuptools插件开发者为了提供一个统一命名约定所做的努力的结果。

安装

使用easy_install

$> easy_install setuptools_git

替代手动安装

$> tar -zxvf setuptools_git-X.Y.Z.tar.gz
$> cd setuptools_git-X.Y.Z
$> python setup.py install

其中X.Y.Z是一个版本号。

使用方法

要激活此插件，您必须首先使用setup.py打包您的Python模块并使用setuptools。前者在distutils手册中有很好的文档。

要使用setuptools代替distutils，只需编辑< span class="docutils literal">setup.py并更改

from distutils.core import setup

到

from setuptools import setup, find_packages

当Setuptools构建源包时，它始终包含由您的版本控制系统跟踪的所有文件，如果它知道如何学习那些文件。

当Setuptools构建二进制包时，您可以通过向您的< cite>setup()调用添加这些参数来请求它包含由您的版本控制系统跟踪的所有文件

setup(...,
      packages=find_packages(),
      include_package_data=True,
      ...)

它将检测如果一个目录包含一个< span class="docutils literal">__init__.py文件，则该目录是一个包。或者，您可以在没有< span class="docutils literal">__init__.py文件的情况下进行操作，并明确告诉Setuptools要处理的包

setup(...,
      packages=["a_package", "another_one"],
      include_package_data=True,
      ...)

此插件让setuptools知道由您的git版本控制系统跟踪的哪些文件。Setuptools附带对cvs和subversion的支持。其他类似此的插件可用于bzr、darcs、monotone、mercurial以及许多其他版本控制系统。

可能会发生这样的情况，即您使用版本控制系统跟踪的文件，您不希望包含在您的包中。在这种情况下，您可以通过在您的< span class="docutils literal">MANIFEST.in中添加指令来防止setuptools打包这些文件，例如

exclude .gitignore
recursive-exclude images *.xcf *.blend

在这个例子中，我们阻止setuptools打包< span class="docutils literal">.gitignore以及位于< span class="docutils literal">images目录下的Gimp和Blender源文件。

要从包中排除的文件也可以在< cite>setup()指令中列出。要执行与上面MANIFEST.in相同的事情，请执行以下操作

setup(...,
      exclude_package_data={'': ['.gitignore'],
                            'images': ['*.xcf', '*.blend']},
      ...)

这里有一个例子

setup(...,
      exclude_package_data={'': ['.gitignore', 'artwork/*'],
                            'model': ['config.py']},
      ...)

需要注意的问题

请注意，为了使此模块正常工作，git和git元数据必须可用。这意味着如果有人试图将您的非git分布（例如tarball）制作成包分布，setuptools将缺乏必要的信息来知道要包含哪些文件。如果有人克隆了您的git存储库但没有安装此插件，也会发生类似的问题。

解决这些问题超出了此插件的范围；如果这些情况是您关注的焦点，您应在您的文档中添加相关的警告。

您可以通过添加一个< cite>setup_requires参数来确保克隆您的git存储库并使用您的setup.py文件的人具有此插件

setup(...,
      setup_requires=[ "setuptools_git >= 0.3", ],
      ...)

更改

1.2; 2017-02-17

• 添加从git标签获取版本的能力（https://github.com/msabramo/setuptools-git/pull/9）

• 如果目录不是由git管理的，则提前返回（https://github.com/msabramo/setuptools-git/pull/10）

• 支持通用wheel（https://github.com/msabramo/setuptools-git/pull/11）

• 优化目录扫描以跳过忽略的目录（https://github.com/msabramo/setuptools-git/pull/12）

参考

• 如何使用Distutils分发Python模块

• Setuptools完整手册

感谢 Zooko O’Whielacronx 对文档的许多改进。