README.rst 2.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273
  1. Use Git commit to determine page date
  2. ======================================
  3. If your blog content is versioned via Git, this plugin will set articles'
  4. and pages' ``metadata['date']`` to correspond to that of the Git commit.
  5. This plugin depends on the ``gitpython`` python package, which can be
  6. installed via::
  7. pip install gitpython
  8. The date is determined via the following logic:
  9. * if a file is not tracked by Git, or a file is staged but never committed
  10. - metadata['date'] = filesystem time
  11. - metadata['updated'] = filesystem time
  12. * if a file is tracked, but no changes in staging area or working directory
  13. - metadata['date'] = first commit time
  14. - metadata['updated'] = last commit time
  15. * if a file is tracked, and has changes in stage area or working directory
  16. - metadata['date'] = first commit time
  17. - metadata['updated'] = filesystem time
  18. When this module is enabled, ``date`` and ``updated`` will be determined
  19. by Git status; no need to manually set in article/page metadata. And
  20. operations like copy and move will not affect the generated results.
  21. If you don't want a given article or page to use the Git time, set the
  22. metadata to ``gittime: off`` to disable it.
  23. You can also set ``GIT_FILETIME_FOLLOW`` to ``True`` in your settings to
  24. make the plugin follow file renames — i.e., ensure the creation date matches
  25. the original file creation date, not the date it was renamed.
  26. FAQ
  27. ---
  28. ### Q. I get a GitCommandError: 'git rev-list ...' when I run the plugin. Why?
  29. Be sure to use the correct gitpython module for your distro's Git binary.
  30. Using the ``GIT_FILETIME_FOLLOW`` option to ``True`` may also make your
  31. problem go away, as that optino uses a different method to find commits.
  32. Some notes on Git
  33. ~~~~~~~~~~~~~~~~~~
  34. * How to check if a file is managed by Git?
  35. .. code-block:: sh
  36. git ls-files $file --error-unmatch
  37. * How to check if a file has changes?
  38. .. code-block:: sh
  39. git diff $file # compare staging area with working directory
  40. git diff --cached $file # compare HEAD with staged area
  41. git diff HEAD $file # compare HEAD with working directory
  42. * How to get commits related to a file?
  43. .. code-block:: sh
  44. git status $file
  45. With ``gitpython`` package, it's easier to parse committed time:
  46. .. code-block:: python
  47. repo = Git.repo('/path/to/repo')
  48. commits = repo.commits(path='path/to/file')
  49. commits[-1].committed_date # oldest commit time
  50. commits[0].committed_date # latest commit time