🚀 Git-Revision-Vite-Plugin

🔥 该插件旨在使用vite脚手架时获取git仓库信息

一、插件的背景和目标

• 背景 - 之前使用webpack打包时要获取git仓库信息一般是使用git-revision-webpack-plugin这个库，但转到vite时发现并没有相对于的库(也发现vite-plugin-git-revision这个库但是发现该库处于初始阶段，功能并不完善)

• 目标 - 尽可能实现git-revision-webpack-plugin等同的功能，保持api与之对齐

• 鸣谢 - 该插件实现参考git-revision-webpack-plugin和vite-plugin-git-revision两个库，特别感谢两个作者

• 声明 - 该插件旨在减化自己工作中重复工作的工具，实现原理简单，自身能力有限，使用者勿喷，如果有好的想法和建议也可在issue中提出

二、插件的使用

Install:

$ npm install -D git-revision-vite-plugin

Add to your vite.config.js:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
  plugins: [
    Vue(),
      GitRevisionVitePlugin()
  ],
};

Use in code:

<script setup lang="ts">
    console.log(GIT_COMMITHASH)
    console.log(GIT_VERSION)
    console.log(GIT_BRANCH)
    console.log(GIT_LASTCOMMITDATETIME)
</script>

三、插件的配置

该插件默认不需要配置，但可以对其进行配置以支持自定义git工作流

version: boolean

如果需要version支持，需要打开此开关（默认为version: true）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            version: true
        })
    ],
};

versionVar: string

如果需要自定义version的注入变量名，需要配置此选项（默认为versionVar: GIT_VERSION）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            versionVar: 'GIT_VERSION'
        })
    ],
};

versionCommand: string

如果需要自定义version的git指令，需要配置此选项（默认为versionCommand: describe --always）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            versionCommand: 'describe --always'
        })
    ],
};

lightweightTags: boolean

如果需要轻量级tag支持，需要打开此开关（默认为lightweightTags: false）。lightweightTags与version是互斥选项，lightweightTags打开时如果git仓库存在tag信息默认显示返回tag，如果git仓库不存在tag信息默认回退返回version信息。lightweightTags与versionCommand选项不能同时设置，否则会抛出错误:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            lightweightTags: true
        })
    ],
};

branch: boolean

如果需要branch支持，需要打开此开关（默认为branch: true）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            branch: true
        })
    ],
};

branchVar: string

如果需要自定义branch的注入变量名，需要配置此选项（默认为branch: GIT_BRANCH）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            branchVar: 'GIT_BRANCH'
        })
    ],
};

branchCommand: string

如果需要自定义branch的git指令，需要配置此选项（默认为branchCommand: rev-parse --abbrev-ref HEAD）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            branchCommand: 'rev-parse --abbrev-ref HEAD'
        })
    ],
};

commitHash: boolean

如果需要commitHash支持，需要打开此开关（默认为commitHash: true）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            commitHash: true
        })
    ],
};

commitHashVar: string

如果需要自定义commitHash的注入变量名，需要配置此选项（默认为commitHashVar: GIT_COMMITHASH）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            commitHashVar: 'GIT_COMMITHASH'
        })
    ],
};

commitHashCommand: string

如果需要自定义commitHash的git指令，需要配置此选项（默认为commitHashCommand: rev-parse HEAD）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            commitHashCommand: 'rev-parse HEAD'
        })
    ],
};

lastCommitDateTime: boolean

如果需要lastCommitDateTime支持，需要打开此开关（默认为lastCommitDateTime: true）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            lastCommitDateTime: true
        })
    ],
};

lastCommitDateTimeVar: string

如果需要自定义commitHash的注入变量名，需要配置此选项（默认为lastCommitDateTimeVar: GIT_LASTCOMMITDATETIME）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            lastCommitDateTimeVar: 'GIT_LASTCOMMITDATETIME'
        })
    ],
};

lastCommitDateTimeCommand: string

如果需要自定义commitHash的git指令，需要配置此选项（默认为lastCommitDateTimeCommand: log -1 --format=%cI）:

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            lastCommitDateTimeCommand: 'log -1 --format=%cI'
        })
    ],
};

gitWorkTree: string

如果需要自定义gitWorkTree，需要配置此选项：

import Vue from '@vitejs/plugin-vue';
import GitRevisionVitePlugin from 'git-revision-vite-plugin';

export default {
    plugins: [
        Vue(),
        GitRevisionVitePlugin({
            gitWorkTree: 'xxxx'
        })
    ],
};

四、关于注入变量名的一些解释

为什么不将信息注入到import.meta.env上？

a. git信息的注入是使用vite -> config -> define选项在编译时全局进行静态替换，但存在一个问题是不支持import.meta.env上的注入，目前发现是这样的(https://cn.vitejs.dev/config/#define)
b. 要实现注入到import.meta.env现阶段的想法是使用vite提供的loadEnv接口，但是还未实际操作，后续版本可能改为此形式

注入的变量名为什么是GIT_打头？

a. 原因是避免注入的全局变量名和其它模块冲突（实际开发中有遇到其它三方库使用了VERSION这个变量名导致在打包时被静态替换出现错误），当然如果你不满意可以通过全局选项修改。

怎么解决全局注入变量名的提示报错？

    // .eslintrc.json - 解决eslint校验报错
    {
      "globals": {
        "GIT_BRANCH": true,
        "GIT_VERSION": true,
        "GIT_COMMITHASH": true,
        "GIT_LASTCOMMITDATETIME": true
      }
    }
    
    // global.d.ts - 解决ts找不到声明变量
    declare const GIT_BRANCH: string
    declare const GIT_COMMITHASH: string
    declare const GIT_VERSION: string
    declare const GIT_LASTCOMMITDATETIME: string   

五、扩展功能

执行自定义git命令runGitDefineCommand

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { runGitDefineCommand } from 'git-revision-vite-plugin'

// tips: 由于runGitDefineCommand返回一个Promise，
// 所以vite配置要使用异步配置(https://cn.vitejs.dev/config/#async-config)
export default defineConfig(async ({ command, mode }) => {
    const tagInfo = await runGitDefineCommand('git tag')

    return {
        plugins: [
            vue(),
            GitRevisionVitePlugin()
        ],
        define: {
            'GIT_TAG': JSON.stringify(tagInfo)
        }
    }
})

// 该功能扩展实现了自定义执行git命令，这样这个插件的可玩性就增加了很多

六、更新记录

    v0.0.11:
      fixed: 修复项目使用type: module, 设置esModule模式调用此插件报错问题，
             参见https://github.com/a1067111756/git-revision-vite-plugin/issues/2