Metadata-Version: 2.0
Name: git-app-version
Version: 1.0.0
Summary: CLI tool to get Git commit informations and store them in a config file
Home-page: https://github.com/csanquer/git-app-version
Author: Charles Sanquer
Author-email: charles.sanquer.pro@gmail.com
License: GPLv3
Keywords: git version commit deploy tools
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: backports.csv
Requires-Dist: click (>=6.0)
Requires-Dist: configparser (>=3.5.0)
Requires-Dist: future
Requires-Dist: gitpython
Requires-Dist: iso8601
Requires-Dist: pytz
Requires-Dist: pyyaml
Requires-Dist: tabulate (>=0.7.0)
Requires-Dist: tzlocal
Requires-Dist: xmltodict
Provides-Extra: dev
Requires-Dist: check-manifest; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: pep8; extra == 'dev'
Requires-Dist: pyinstaller (>=3.2pylint); extra == 'dev'
Requires-Dist: pypandoc; extra == 'dev'
Requires-Dist: versioneer; extra == 'dev'
Requires-Dist: yapf; extra == 'dev'
Provides-Extra: test
Requires-Dist: mock; extra == 'test'
Requires-Dist: pytest (>=3.0); extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: tox; extra == 'test'

Git App Version
===============

| |PyPI version|
| |travis-build|
| |scrutinizer-quality|
| |scrutinizer-coverage|

A CLI tool written in Python to fetch Git commit informations and store
them in a config file.

supported formats :

-  JSON
-  YAML
-  XML
-  INI
-  CSV
-  Shell script variables

Typical usecase : when deploying, run this command and import the git
version config file.

Requirements
------------

-  Python 2.7 or >= 3.3
-  python pip package tool

Installation
------------

Just run :

.. code:: sh

    pip install git-app-version

Usage
-----

Help
~~~~

To get help

.. code:: sh

    git-app-version -h

Help result

.. code:: txt

    Usage: git-app-version [OPTIONS] [REPOSITORY] [COMMIT]

      Get Git commit informations and store them in a config file

      REPOSITORY git repository path, Default is the current directory.
      COMMIT     git commit to check, Default is HEAD.

    Options:
      -V, --version
      -q, --quiet                     silent mode
      -o, --output TEXT               output file path (without extension).
                                      Default is '<repository-path>/version'.
      -f, --format [all|json|yml|xml|ini|csv|sh]
                                      output file format and extension, use 'all'
                                      to output all format, can be set several
                                      times , Default is json.
      -n, --namespace TEXT            namespace like notation in version file, use
                                      dot separator to segment namespaces e.g.:
                                      'foo.bar.git'. Default is 'app_version' for
                                      XML and INI and no namespace for JSON and
                                      YAML. Never used for CSV or Shell file.
      -m, --meta METADATA             meta data to add, format = "<key>=<value>",
                                      can be set several times
      -d, --csv-delimiter TEXT        CSV delimiter, default=","
      -e, --csv-eol [lf|crlf]         CSV end of line, lf = Unix new line, crlf =
                                      windows new line, default=lf
      -u, --csv-quote TEXT            CSV quoting character, default='"'
      -h, --help                      Show this message and exit.

Get Commit Informations
~~~~~~~~~~~~~~~~~~~~~~~

To store git commit informations into a json file

.. code:: sh

    # git-app-version -o <output-file-without-extension> -f <file-format> <my-git-repository>
    git-app-version -o version -f json

output :

.. code:: txt

    Git commit :
    ----------------  ----------------------------------------
    abbrev_commit     40aaf83
    author_date       2015-09-05T16:14:16+0000
    author_email      paul.durand@example.com
    author_name       Paul Durand
    author_timestamp  1441469656
    branches          master develop
    commit_date       2015-09-05T16:14:16+0000
    commit_timestamp  1441469656
    committer_email   paul.durand@example.com
    committer_name    Paul Durand
    deploy_date       2016-06-21T09:33:01+0000
    deploy_timestamp  1466501581
    full_commit       40aaf83894b98898895d478f8b7cc4a866b1d62c
    message           new feature
    top_branches      master
    version           v1.1.0-3-g439e52
    ----------------  ----------------------------------------
    written to :
    <my-git-repository>/version.json

This will generate a version.json file in the current directory (if this
directory is a git repository).

You can generate several format at once :

.. code:: sh

    git-app-version -o version -f json -f yml -f xml -f ini -f sh

Metadata : adding custom fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can add custom metadata fields with the --meta / -m option (can be
used several times) :

.. code:: sh

    git-app-version -m foo=bar -m custom_key=custom_value

output :

.. code:: txt

    Git commit :
    ----------------  ----------------------------------------
    abbrev_commit     40aaf83
    author_date       2015-09-05T16:14:16+0000
    author_email      paul.durand@example.com
    author_name       Paul Durand
    author_timestamp  1441469656
    branches          master develop
    commit_date       2015-09-05T16:14:16+0000
    commit_timestamp  1441469656
    committer_email   paul.durand@example.com
    committer_name    Paul Durand
    custom_key        custom_value
    deploy_date       2016-06-21T09:33:01+0000
    deploy_timestamp  1466501581
    foo               bar
    full_commit       40aaf83894b98898895d478f8b7cc4a866b1d62c
    message           new feature
    top_branches      master
    version           v1.1.0-3-g439e52
    ----------------  ----------------------------------------
    written to :
    <my-git-repository>/version.json

Commit informations fields
~~~~~~~~~~~~~~~~~~~~~~~~~~

-  **full\_commit** : Git SHA1 commit hash,

   *e.g.: 40aaf83894b98898895d478f8b7cc4a866b1d62c*

-  **abbrev\_commit** : Git SHA1 commit hash abbrev notation (x
   significant first characters),

   *e.g.: 40aaf83*

-  **version** : result of the command ``git describe --tags --always``,
   see `git-describe <https://git-scm.com/docs/git-describe>`__, if no
   version is found, the abbrev commit will be used per default

   *e.g.: v1.1.0-3-g439e52*

-  **message** : Git commit message
-  **commit\_date** : Git commit date in
   `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ format,

   *e.g.: 2016-03-01T09:33:33+0000*

-  **commit\_timestamp** : Git commit date in timestamp format,

   *e.g.: 1456824813*

-  **author\_date** : Git author date in
   `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ format,

   *e.g.: 2016-03-02T11:33:45+0000*

-  **author\_timestamp** : Git author date in timestamp format,

   *e.g.: 1456918425*

-  **deploy\_date** : current date (when running the tool) in
   `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ format,

   *e.g.: 2016-03-02T11:33:45+0000*

-  **deploy\_timestamp** : current date (when running the tool) in
   timestamp format,

   *e.g.: 1456918425*

-  **branches** : branches which the commit belongs,

   *e.g.: ['master', 'develop']*

-  **top\_branches** : branches where the commit is the HEAD commit,

   *e.g.: ['master']*

-  **committer\_name** : Git committer name,

   *e.g.: Paul Durand*

-  **committer\_email** : Git committer email,

   *e.g.: paul.durand@example.com*

-  **author\_name** : Git author name,

   *e.g.: Paul Durand*

-  **author\_email** : Git author email,

   *e.g.: paul.durand@example.com*

File formats
~~~~~~~~~~~~

-  json

   without namespace

   .. code:: sh

       git-app-version -f json

   result

   .. code:: json

       {
         "version": "v1.1.0-3-g439e52",
         "full_commit": "40aaf83894b98898895d478f8b7cc4a866b1d62c",
         "abbrev_commit": "40aaf83",
         "branches": [
           "develop",
           "master"
         ],
         "top_branches": [
           "master"
         ],
         "committer_email": "paul.durand@example.com",
         "committer_name": "Paul Durand",
         "author_name": "Paul Durand",
         "author_email": "paul.durand@example.com",
         "commit_date": "2015-09-05T16:14:16+0000",
         "commit_timestamp": "1441469656",
         "author_date": "2015-09-05T16:14:16+0000",
         "author_timestamp": "1441469656",
         "deploy_date": "2016-06-21T09:33:01+0000",
         "deploy_timestamp": "1466501581",
         "message": "new feature"

       }

   with namespace

   .. code:: sh

       git-app-version -f json -n git.infos

   result

   .. code:: json

       {
         "git": {
           "infos": {
             "version": "v1.1.0-3-g439e52",
             "full_commit": "40aaf83894b98898895d478f8b7cc4a866b1d62c",
             "abbrev_commit": "40aaf83",
             "branches": [
               "develop",
               "master"
             ],
             "top_branches": [
               "master"
             ],
             "committer_email": "paul.durand@example.com",
             "committer_name": "Paul Durand",
             "author_name": "Paul Durand",
             "author_email": "paul.durand@example.com",
             "commit_date": "2015-09-05T16:14:16+0000",
             "commit_timestamp": "1441469656",
             "author_date": "2015-09-05T16:14:16+0000",
             "author_timestamp": "1441469656",
             "deploy_date": "2016-06-21T09:33:01+0000",
             "deploy_timestamp": "1466501581",
             "message": "new feature"
           }
         }
       }

-  yml

   without namespace

   .. code:: sh

       git-app-version -f yml

   result

   .. code:: yml

       ---
       'version': 'v1.1.0-3-g439e52'
       'full_commit': '40aaf83894b98898895d478f8b7cc4a866b1d62c'
       'abbrev_commit': '40aaf83'
       'committer_name': 'Paul Durand'
       'committer_email': 'paul.durand@example.com'
       'author_name': 'Paul Durand'
       'author_email': 'paul.durand@example.com'
       'commit_date': '2015-09-05T16:14:16+0000'
       'commit_timestamp': '1441469656'
       'author_date': '2015-09-05T16:14:16+0000'
       'author_timestamp': '1441469656'
       'deploy_date': '2016-06-21T09:32:57+0000'
       'deploy_timestamp': '1466501577'
       'message': 'new feature'
       'branches':
       - 'develop'
       - 'master'
       'top_branches':
       - 'master'

   with namespace

   .. code:: sh

       git-app-version -f yml -n git.infos

   result

   .. code:: yml

       ---
       'git':
         'infos':
           'version': 'v1.1.0-3-g439e52'
           'full_commit': '40aaf83894b98898895d478f8b7cc4a866b1d62c'
           'abbrev_commit': '40aaf83'
           'committer_name': 'Paul Durand'
           'committer_email': 'paul.durand@example.com'
           'author_name': 'Paul Durand'
           'author_email': 'paul.durand@example.com'
           'commit_date': '2015-09-05T16:14:16+0000'
           'commit_timestamp': '1441469656'
           'author_date': '2015-09-05T16:14:16+0000'
           'author_timestamp': '1441469656'
           'deploy_date': '2016-06-21T09:32:57+0000'
           'deploy_timestamp': '1466501577'
           'message': 'new feature'
           'branches':
           - 'develop'
           - 'master'
           'top_branches':
           - 'master'

-  xml

   with default namespace

   .. code:: sh

       git-app-version -f xml

   result

   .. code:: xml

       <?xml version='1.0' encoding='UTF-8'?>
       <app_version>
         <version>v1.1.0-3-g439e52</version>
         <full_commit>40aaf83894b98898895d478f8b7cc4a866b1d62c</full_commit>
         <abbrev_commit>40aaf83</abbrev_commit>
         <commit_date>2015-09-05T16:14:16+0000</commit_date>
         <commit_timestamp>1441469656</commit_timestamp>
         <author_date>2015-09-05T16:14:16+0000</author_date>
         <author_timestamp>1441469656</author_timestamp>
         <deploy_date>2016-06-21T09:32:53+0000</deploy_date>
         <deploy_timestamp>1466501573</deploy_timestamp>
         <committer_name>Paul Durand</committer_name>
         <committer_email>paul.durand@example.com</committer_email>
         <author_name>Paul Durand</author_name>
         <author_email>paul.durand@example.com</author_email>
         <message>new feature</message>
         <branches>develop</branches>
         <branches>master</branches>
         <top_branches>master</top_branches>
       </app_version>

   with namespace

   .. code:: sh

       git-app-version -f xml -n git.infos

   result

   .. code:: xml

       <?xml version='1.0' encoding='UTF-8'?>
       <git>
         <infos>
           <version>v1.1.0-3-g439e52</version>
           <full_commit>40aaf83894b98898895d478f8b7cc4a866b1d62c</full_commit>
           <abbrev_commit>40aaf83</abbrev_commit>
           <commit_date>2015-09-05T16:14:16+0000</commit_date>
           <commit_timestamp>1441469656</commit_timestamp>
           <author_date>2015-09-05T16:14:16+0000</author_date>
           <author_timestamp>1441469656</author_timestamp>
           <deploy_date>2016-06-21T09:32:53+0000</deploy_date>
           <deploy_timestamp>1466501573</deploy_timestamp>
           <committer_name>Paul Durand</committer_name>
           <committer_email>paul.durand@example.com</committer_email>
           <author_name>Paul Durand</author_name>
           <author_email>paul.durand@example.com</author_email>
           <message>new feature</message>
           <branches>develop</branches>
           <branches>master</branches>
           <top_branches>master</top_branches>
         </infos>
       </git>

-  ini

   with default namespace

   .. code:: sh

       git-app-version -f ini

   result

   .. code:: ini

       [app_version]
       version = v1.1.0-3-g439e52
       full_commit = 40aaf83894b98898895d478f8b7cc4a866b1d62c
       abbrev_commit = 40aaf83
       commit_date = 2016-03-01T09:33:33+0000
       commit_timestamp = 1456824813
       author_date = 2016-03-01T09:33:33+0000
       author_timestamp = 1456824813
       deploy_date = 2016-03-02T11:33:45+0000
       deploy_timestamp = 1456918425
       message = new feature
       author_name = Paul Durand
       author_email = paul.durand@example.com
       committer_name = Paul Durand
       committer_email = paul.durand@example.com
       top_branches = ['master']
       branches = ['master','develop']

   with namespace

   .. code:: sh

       git-app-version -f ini -n git.infos

   result

   .. code:: ini

       [git.infos]
       version = v1.1.0-3-g439e52
       full_commit = 40aaf83894b98898895d478f8b7cc4a866b1d62c
       abbrev_commit = 40aaf83
       commit_date = 2016-03-01T09:33:33+0000
       commit_timestamp = 1456824813
       author_date = 2016-03-01T09:33:33+0000
       author_timestamp = 1456824813
       deploy_date = 2016-03-02T11:33:45+0000
       deploy_timestamp = 1456918425
       message = new feature
       author_name = Paul Durand
       author_email = paul.durand@example.com
       committer_name = Paul Durand
       committer_email = paul.durand@example.com
       top_branches = ['master']
       branches = ['master','develop']

-  csv

   you can configure CSV format with the option --csv-delimiter ,
   --csv-eol and --csv-quote

   .. code:: sh

       git-app-version -f csv --csv-delimiter ',' --csv-eol lf --csv-quote '"'

   result

   .. code:: csv

       version,v1.1.0-3-g439e52
       full_commit,40aaf83894b98898895d478f8b7cc4a866b1d62c
       abbrev_commit,40aaf83
       commit_date,2016-03-01T09:33:33+0000
       commit_timestamp,1456824813
       author_date,2016-03-01T09:33:33+0000
       author_timestamp,1456824813
       deploy_date,2016-03-02T11:33:45+0000
       deploy_timestamp,1456918425
       message,new feature
       author_name,Paul Durand
       author_email,paul.durand@example.com
       committer_name,Paul Durand
       committer_email,paul.durand@example.com
       top_branches,"['master']"
       branches,"['master','develop']"

-  sh (shell script variables)

   .. code:: sh

       git-app-version -f sh

   result

   .. code:: sh

       version="v1.1.0-3-g439e52"
       full_commit="40aaf83894b98898895d478f8b7cc4a866b1d62c"
       abbrev_commit="40aaf83"
       commit_date="2016-03-01T09:33:33+0000"
       commit_timestamp="1456824813"
       author_date="2016-03-01T09:33:33+0000"
       author_timestamp="1456824813"
       deploy_date="2016-03-02T11:33:45+0000"
       deploy_timestamp="1456918425"
       message="new feature"
       author_name="Paul Durand"
       author_email="paul.durand@example.com"
       committer_name="Paul Durand"
       committer_email="paul.durand@example.com"
       top_branches="['master']"
       branches="['master','develop']"

Licensing
---------

Project under GPL v3 License

Copyright (C) 2016 Charles Sanquer

.. |PyPI version| image:: https://badge.fury.io/py/git-app-version.svg
   :target: https://badge.fury.io/py/git-app-version
.. |travis-build| image:: https://travis-ci.org/csanquer/git-app-version.svg?branch=master
   :target: https://travis-ci.org/csanquer/git-app-version
.. |scrutinizer-quality| image:: https://scrutinizer-ci.com/g/csanquer/git-app-version/badges/quality-score.png?b=master
   :target: https://scrutinizer-ci.com/g/csanquer/git-app-version/?branch=master
.. |scrutinizer-coverage| image:: https://scrutinizer-ci.com/g/csanquer/git-app-version/badges/coverage.png?b=master
   :target: https://scrutinizer-ci.com/g/csanquer/git-app-version/?branch=master


