- 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:

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

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

```json
[{
  "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:

```js
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:

```js
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](#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.

```js
// server
module.exports = {
  plugins: ['@vuepress/last-updated']
  // show deprecation warning
}
```
```js
// 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