Use git commit to determine page date
======================================

If the blog content is managed by git repo, this plugin will set articles'
and pages' ``metadata['date']`` according to git commit. This plugin depends
on python package ``gitpython``, install::

    pip install gitpython

The determine logic will works so:

* if a file is not tracked by git, or a file is staged but never commited
    - metadata['date'] = fs time
    - metadata['updated'] = fs time
* if a file is tracked, but no changes in stage area or work dir
    - metadata['date'] = first commit time
    - metadata['updated'] = last commit time
* if a file is tracked, and has changes in stage area or work dir
    - metadata['date'] = first commit time
    - metadata['updated'] = fs time

When this module is enabled, ``date`` and ``updated`` will be set automatically
by git status, no need to manually set in article/page's metadata. And
operations like copy, move will not affect the generated results.

If some article or page doesn't like to use git time, set a ``gittime: off``
metadata to disable it.

Some notes on git
~~~~~~~~~~~~~~~~~~

* How to check if a file is managed?

.. code-block:: sh

   git ls-files $file --error-unmatch

* How to check if a file has changes?

.. code-block:: sh

   git diff $file            # compare staged area with working directory
   git diff --cached $file   # compare HEAD with staged area
   git diff HEAD $file       # compare HEAD with working directory

* How to get commits related to a file?

.. code-block:: sh

   git status $file

with ``gitpython`` package, it's easier to parse commited time:

.. code-block:: python

   repo = Git.repo('/path/to/repo')
   commits = repo.commits(path='path/to/file')
   commits[-1].committed_date    # oldest commit time
   commits[0].committed_date     # latest commit time