()                                                                            ()

[1mName[0m
      -

[1mAbout[0m
     This  is  a  plugin  for  setuptools that enables git integration. Once in‐
     stalled, Setuptools can be told to include in a  package  distribution  all
     the  files  tracked  by  git.  This is an alternative to explicit inclusion
     specifications with [1mMANIFEST.in[22m.

     A package distribution here refers to  a  package  that  you  create  using
     setup.py, for example:

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

     This  package  was formerly known as gitlsfiles. The name change is the re‐
     sult of an effort by the setuptools plugin developers to provide a  uniform
     naming convention.

[1mInstallation[0m
     With easy_install:

        $> easy_install setuptools_git

     Alternative manual installation:

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

     Where X.Y.Z is a version number.

[1mUsage[0m
     To  activate  this  plugin,  you must first package your python module with
     [1msetup.py [22mand use setuptools. The former is well documented in the distutils
     manual <http://docs.python.org/dist/dist.html>.

     To use setuptools instead of distutils, just edit [1msetup.py [22mand change:

        from distutils.core import setup

     to:

        from setuptools import setup, find_packages

     When Setuptools builds a source  package,  it  always  includes  all  files
     tracked  by  your  revision  control  system, if it knows how to learn what
     those files are.

     When Setuptools builds a binary package, you can  ask  it  to  include  all
     files  tracked by your revision control system, by adding these argument to
     your invocation of [4msetup()[24m:

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

     which will  detect  that  a  directory  is  a  package  if  it  contains  a
     [1m__init__.py  [22mfile.  Alternatively, you can do without [1m__init__.py [22mfiles and
     tell Setuptools explicitly which packages to process:

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

     This plugin lets setuptools know what files are tracked by your  git  revi‐
     sion  control  tool.  Setuptools ships with support for cvs and subversion.
     Other plugins like this one are available for bzr, darcs, monotone, mercur‐
     ial, and many others.

     It might happen that you track files with your revision control system that
     you don't want to include in your packages.  In that case, you can  prevent
     setuptools from packaging those files with a directive in your [1mMANIFEST.in[22m,
     for example:

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

     In  this  example,  we prevent setuptools from packaging [1m.gitignore [22mand the
     Gimp and Blender source files found under the [1mimages [22mdirectory.

     Files to exclude from the package can also be listed in the [4msetup()[24m  direc‐
     tive.  To do the same as the MANIFEST.in above, do:

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

     Here is another example:

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

[1mGotchas[0m
     Be  aware  that for this module to work properly, git and the git meta-data
     must be available. That means that if someone tries to make a package  dis‐
     tribution out of a non-git distribution of yours, say a tarball, setuptools
     will lack the information necessary to know which files to include. A simi‐
     lar  problem will happen if someone clones your git repository but does not
     install this plugin.

     Resolving those problems is out of the scope of this plugin; you should add
     relevant warnings to your documentation if those situations are  a  concern
     to you.

     You  can make sure that anyone who clones your git repository and uses your
     setup.py file has this plugin by adding a [4msetup_requires[24m argument:

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

[1mChanges[0m
   [1m1.2; 2017-02-17[0m
        • Add  ability  to  get  version  from  git  tags  (<https://github.com/
          msabramo/setuptools-git/pull/9>)

        • Return early if a directory isn't managed by git (<https://github.com/
          msabramo/setuptools-git/pull/10>)

        • Support universal wheels (<https://github.com/msabramo/setuptools-git/
          pull/11>)

        • Optimize  directory  scanning  to  skip ignored directories (<https://
          github.com/msabramo/setuptools-git/pull/12>)

[1mReferences[0m
     • How to distribute Python modules with Distutils  <http://docs.python.org/
       dist/dist.html>

     • Setuptools   complete   manual  <http://peak.telecommunity.com/DevCenter/
       setuptools>

     Thanks to Zooko O'Whielacronx <https://bitbucket.org/zooko>  for  many  im‐
     provements to the documentation.

                                                                              ()
