Skip to main content

ShowCommits preprocessor for Foliant.

Project description

ShowCommits Preprocessor

ShowCommits is a preprocessor that appends the history of Git commits corresponding to the current processed file to its content.

Installation

$ pip install foliantcontrib.showcommits

Config

To enable the preprocessor, add showcommits to preprocessors section in the project config:

preprocessors:
    - showcommits

The preprocessor has a number of options with the following default values:

preprocessors:
    - showcommits:
        repo_path: !rel_path ./    # Path object that points to the current Foliant project’s top-level (“root”) directory when the preprocessor initializes
        remote_name: origin
        self-hosted: gitlab
        protocol: https
        position: after_content
        date_format: year_first
        template: |
            ## File History

            {{startcommits}}
            Commit: [{{hash}}]({{url}}), author: [{{author}}]({{email}}), date: {{date}}

            {{message}}

            ```diff
            {{diff}}
            ```
            {{endcommits}}
        targets: []

repo_path : Path to the locally cloned copy of the Git repository that the current Foliant project’s files belong to.

remote_name : Identifier of remote repository; in most cases you don’t need to override the default value.

self-hosted : String that defines the rules of commit’s web URL anchor generation when a self-hosted Git repositories management system with web interface is used. Supported values are: github for GitHub, gitlab for GitLab, and bitbucket for BitBucket. If the repo fetch URL hostname is github.com, gitlab.com, or bitbucket.org, the corresponding rules are applied automatically.

protocol : Web interface URL prefix of a repos management system. Supported values are https and http.

position : String that defines where the history of commits should be placed. Supported values are: after_content for concatenating the history with the currently processed Markdown file content, and defined_by_tag for replacing the tags <<commits></commits> with the history.

date_format : Output date format. If the default value year_first is used, the date “December 11, 2019” will be represented as 2019-12-11. If the day_first value is used, this date will be represented as 11.12.2019.

template : Template to render the history of commits. If the value is a string that contains one or more newlines (\n) or double opening curly braces ({{), it is interpreted as a template itself. If the value is a string without newlines and any double opening curly braces, or a Path object, it is interpreted as a path to the file that contains a template. Template syntax is described below.

targets : Allowed targets for the preprocessor. If not specified (by default), the preprocessor applies to all targets.

Usage

You may override the default template to customize the commits history formatting and rendering. Feel free to use Markdown syntax, HTML, CSS, and JavaScript in your custom templates.

In templates, a number of placeholders is supported.

{{startcommits}} : Beginning of the list of commits that is rendered within a loop. Before this placeholder, you may use some common stuff like an introducing heading or a stylesheet.

{{endcommits}} : End of the list of commits. After this placeholder, you also may use some common stuff like a paragraph of text or a script.

The following placeholders affect only between the {{startcommits}} and {{endcommits}}.

{{hash}} : First 8 digits of the commit hash, e.g. deadc0de.

{{url}} : Web URL of commit with an anchor that points to the certain file, e.g. https://github.com/foliant-docs/foliant/commit/67138f7c#diff-478b1f78b2146021bce46fbf833eb636. If you don’t use a repos management system with web interface, you don’t need this placeholder.

{{author}} : Author name, e.g. Artemy Lomov.

{{email}} : Author email, e.g. artemy@lomov.ru.

{{date}} : Formatted date, e.g. 2019-12-11.

{{message}} : Commit message, e.g. Bump version to 1.0.1..

{{diff}} : Diff between the currently processed Markdown file at a certain commit and the same file at the previous state.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foliantcontrib.showcommits-1.0.1.tar.gz (6.0 kB view details)

Uploaded Source

Built Distribution

foliantcontrib.showcommits-1.0.1-py3-none-any.whl (7.1 kB view details)

Uploaded Python 3

File details

Details for the file foliantcontrib.showcommits-1.0.1.tar.gz.

File metadata

  • Download URL: foliantcontrib.showcommits-1.0.1.tar.gz
  • Upload date:
  • Size: 6.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.11.1 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.8

File hashes

Hashes for foliantcontrib.showcommits-1.0.1.tar.gz
Algorithm Hash digest
SHA256 835614247b8c320cdacb879a495de734b729f2842a67aa068fa423e47ef660fe
MD5 82afdeba4f0fc59536ebc75212d968fb
BLAKE2b-256 e21e79649426354f3f2f4d12c882073b5b8d206193f16cc8150d72d553038dc2

See more details on using hashes here.

File details

Details for the file foliantcontrib.showcommits-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: foliantcontrib.showcommits-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 7.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.11.1 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.8

File hashes

Hashes for foliantcontrib.showcommits-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 b9c58db85e5c0b6f279b161e10ca173a27291fb6a515988d3b4f6cab8474cdfb
MD5 16f60f394611940dbc82b0225ec4fba4
BLAKE2b-256 565e55e404a1b91515457f2e3861c4b6d1ed7dc8f76f3d9d521ca3a9b1cff463

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page