mirror of
https://github.com/wahyd4/vuepress.git
synced 2026-08-09 21:36:16 +10:00
127 lines
3.3 KiB
Markdown
127 lines
3.3 KiB
Markdown
- 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
|