• Start Date: 2019-03-06
• RFC PR: (leave this empty)
• VuePress Issue: (leave this empty)

Summary

A new official plugin @vuepress/plugin-git-log featured with more computed properties to be mixed in.

Basic example

1. Apply the plugin @vuepress/git-log.
2. It will provide a computed property $git, with following attributes:
   • $git.updated: the last updating time for this page
   • $git.created: the first creating time for this page
   • $git.author: the author for this page
   • $git.contributors: contributors for this page
   • $git.commits: detailed informations of commits to this page

Motivation

Although last-updated works well, git-log provides more information. Such plugin will provide remarkable convenience to users, because it automatically generates some necessary meta information.

Detailed design

Computed Properties

We will get all computed properties through a command line like this:

git log --format="%h %at %ct %an"

Passing the result to client, we will get a $git.commits like this:

[{
  "hash": "aabbccd",
  "authorTime": 11111111,
  "commitTime": 22222222,
  "author": "fooooooo"
}, {
  "hash": "ffeeddc",
  "authorTime": 33333333,
  "commitTime": 44444444,
  "author": "baaaaaar"
}]

And other computed properties can be derived from this.

Options

formatTime

A function to format unix time. It may have two arguments: time and lang. The default value will be:

function formatTime (timestamp, lang) {
  return new Date(timestamp).toLocaleString(lang)
}

additionalProps

Aside from some properties listed above, we can add some custom properties through this option:

module.exports = {
  plugins: [
    ['@vuepress/git-log', {
      additionalProps: {
        subject: '%s',
        authorEmail: '%ae',
      }
    }]
  ]
}

additionalArgs

A string or an array of strings to include all the additional args. The default value will be '--no-merge'.

onlyFirstAndLastCommit

If set to true, this plugin will only look for the first and last commit, which may save lots of time. The default value is false.

However, setting this option to also means you will have no access to $git.contributors and $git.commits.

Drawbacks

• It will replace existing plugin @vuepress/plugin-last-updated, which may lead to a breaking change (also see adoption-strategy).
• It will cost more time to get all the detailed informations on a large git project than in the past with default options (because onlyFirstAndLastCommit is false).

Alternatives

Publish multiple packages like @vuepress/plugin-last-updated. But in that case, we may need lots of command lines, which may seriously affect performance.

Adoption strategy

We will deprecate @vuepress/plugin-last-updated after several months. Before then, we will automatically import @vuepress/plugin-git-log in @vuepress/plugin-last-updated and support both functionality.

// server
module.exports = {
  plugins: ['@vuepress/last-updated']
  // show deprecation warning
}

// client
export default {
  created () {
    console.log(this.$lastUpdated) // show deprecation warning
    console.log(this.$git.updated)
  }
}

How we teach this

Through official plugin documentation (i.e. /plugin/official/plugin-git-log.html).

Unresolved questions

N/A