T Comm

引入

import {
  IGitFullInfo,
  getAllGitRepo,
  execAsync,
  checkSingleRepo,
  checkGitClean,
  checkGitCleanSync,
  parseConfigWithOrigin,
  parseGitProject,
  getGitFullInfo,
  isInGitRepo,
  getGitCurBranch,
  getGitCommitMessage,
  getGitCommitInfo,
  getGitLastTag,
  getGitCommitsBeforeTag,
  getGitAuthor,
  reCloneGitRemote
} from 't-comm';

// 不支持 tree-shaking 的项目
import {
  IGitFullInfo,
  getAllGitRepo,
  execAsync,
  checkSingleRepo,
  checkGitClean,
  checkGitCleanSync,
  parseConfigWithOrigin,
  parseGitProject,
  getGitFullInfo,
  isInGitRepo,
  getGitCurBranch,
  getGitCommitMessage,
  getGitCommitInfo,
  getGitLastTag,
  getGitCommitsBeforeTag,
  getGitAuthor,
  reCloneGitRemote
} from 't-comm/lib/git/index';

// 只支持 ESM 的项目
import {
  IGitFullInfo,
  getAllGitRepo,
  execAsync,
  checkSingleRepo,
  checkGitClean,
  checkGitCleanSync,
  parseConfigWithOrigin,
  parseGitProject,
  getGitFullInfo,
  isInGitRepo,
  getGitCurBranch,
  getGitCommitMessage,
  getGitCommitInfo,
  getGitLastTag,
  getGitCommitsBeforeTag,
  getGitAuthor,
  reCloneGitRemote
} from 't-comm/es/git/index';

`IGitFullInfo`

描述：一站式 git 仓库信息（贴近 CI / 构建上报场景的完整字段）

参数：

IGitFullInfo
- .project : string | null
- .remoteUrl : string | null
- .branch : string | null
- .commitSha : string | null
- .authorName : string | null
- .authorEmail : string | null
- .userName : string | null
- .userEmail : string | null
- .userScope : 'local' | 'global' | 'none'

`iGitFullInfo.project` : `string` | `null`

项目标识，如 pmd-mobile/pixui/pubgm-official（remoteUrl 解析失败时为 null）

Kind: instance property of IGitFullInfo

`iGitFullInfo.remoteUrl` : `string` | `null`

原始 remote URL

Kind: instance property of IGitFullInfo

`iGitFullInfo.branch` : `string` | `null`

当前分支

Kind: instance property of IGitFullInfo

`iGitFullInfo.commitSha` : `string` | `null`

最近一次提交 sha（40 位）

Kind: instance property of IGitFullInfo

`iGitFullInfo.authorName` : `string` | `null`

最近一次提交作者姓名

Kind: instance property of IGitFullInfo

`iGitFullInfo.authorEmail` : `string` | `null`

最近一次提交作者邮箱

Kind: instance property of IGitFullInfo

`iGitFullInfo.userName` : `string` | `null`

当前 git 登录用户名（仓库级优先 → 全局）

Kind: instance property of IGitFullInfo

`iGitFullInfo.userEmail` : `string` | `null`

当前 git 登录用户邮箱

Kind: instance property of IGitFullInfo

`iGitFullInfo.userScope` : `'local'` | `'global'` | `'none'`

user.name / user.email 来源

Kind: instance property of IGitFullInfo

`getAllGitRepo(root)`

描述：获取所有 git 仓库

参数：

参数名	类型	描述
root	`string`	根路径

返回: array

路径列表

示例

getAllGitRepo('/root/yang');

[
  {
    root: '/root',
    origin: 'git@git.address',
  }
]

`execAsync()`

描述：异步执行命令，返回 stdout 字符串

参数：

`checkSingleRepo(subDir, chalk)`

描述：检查单个 git 仓库的状态（是否 clean、是否已 push）

参数：

参数名	类型	描述
subDir	`string`	git 仓库目录路径
chalk	`\*`	chalk 实例

`checkGitClean(dir)`

描述：异步并行检查目录下所有 git 仓库的工作区状态相比同步版本，在仓库数量较多时有显著的性能提升

参数：

参数名	描述
dir	要检查的父目录路径

示例

// 并行检查 ~/Documents/git 下所有子仓库
await checkGitClean('/Users/foo/Documents/git');
// 控制台会输出：
// [not clean]   /Users/foo/Documents/git/repoA
// [not push]    /Users/foo/Documents/git/repoB

`checkGitCleanSync(dir)`

描述：同步版本，保持向后兼容

参数：

参数名	描述
dir	要检查的父目录路径

示例

checkGitCleanSync('/Users/foo/Documents/git');
// 同步依次检查，仓库有变动或未推送会打印警告

`parseConfigWithOrigin()`

描述：解析 git config --show-origin --get key 的输出，格式：file:<配置文件路径>\t<值> 通过配置文件路径判断来源：

含 .git/ 或 config.worktree → 'local'
其它（~/.gitconfig、/etc/gitconfig 等） → 'global'

参数：

`parseGitProject()`

描述：将 git remote URL 解析成 group/subgroup/project 形式。支持以下格式：

git@git.woa.com:pmd-mobile/pixui/pubgm-official.git
ssh://git@git.woa.com:22/pmd-mobile/pixui/pubgm-official.git
https://git.woa.com/pmd-mobile/pixui/pubgm-official.git
http://git.woa.com/pmd-mobile/pixui/pubgm-official

参数：

示例

parseGitProject('git@git.woa.com:pmd-mobile/pixui/pubgm-official.git');
// => 'pmd-mobile/pixui/pubgm-official'

`getGitFullInfo(root)`

描述：一次性收集仓库的完整 git 信息（remote / 分支 / 最近一次提交作者 / 当前登录用户）。与 getGitCommitInfo 的差异：

提供 40 位 commitSha（getGitCommitInfo.hash 是 short id）
提供 authorEmail
提供 当前 git 登录用户（user.name / user.email，仓库级优先 → 全局 → 环境变量）并标记来源 userScope
提供 project 字段（自动解析 remoteUrl 为 group/sub/project）

任意一项失败均不影响其它字段。

参数：

参数名	描述
root	git 仓库根目录，默认 `process.cwd()`

示例

import { getGitFullInfo } from 't-comm';

const info = getGitFullInfo();
// {
//   project: 'pmd-mobile/pixui/pubgm-official',
//   remoteUrl: 'git@git.woa.com:pmd-mobile/pixui/pubgm-official.git',
//   branch: 'develop',
//   commitSha: '33c75cb8e78a7388c357749234d46b731daead09',
//   authorName: 'mobilehelper',
//   authorEmail: 'mobilehelper@tencent.com',
//   userName: 'novlan1',
//   userEmail: 'novlan1@tencent.com',
//   userScope: 'global',
// }

`isInGitRepo(root)`

描述：判断指定路径（默认 process.cwd()）是否在 git 仓库中。实现方式：从给定目录起向上递归查找 .git（目录或文件，后者用于 worktree / submodule 场景）。不会执行任何 git 命令，纯文件系统判断，零副作用、不会刷屏报错。结果会按绝对路径缓存，重复调用近乎零开销。

参数：

参数名	描述
root	起始目录，默认为 `process.cwd()`

返回: 是否在 git 仓库内

示例

if (isInGitRepo()) {
  const branch = getGitCurBranch();
}

`getGitCurBranch()`

描述：获取当前分支

参数：

返回: string

分支名称

示例

typescript

getGitCurBranch()

// => master

`getGitCommitMessage(root, mergeCommit, splitMessage)`

描述：获取提交信息

参数：

参数名	类型	描述
root	`string`	根路径
mergeCommit	`boolean`	是否包含 merge 的提交
splitMessage	`boolean`	是否去掉提交信息的前缀

返回: string

提交信息

示例

getGitCommitMessage()
// '优化一部分文档'

`getGitCommitInfo(root, mergeCommit, splitMessage)`

描述：获取提交信息

参数：

参数名	类型	描述
root	`string`	根路径
mergeCommit	`boolean`	是否包含 merge 的提交
splitMessage	`boolean`	是否去掉提交信息的前缀

返回: Object

提交对象

示例

getGitCommitInfo()
{
  author: 'novlan1',
  message: ' 优化一部分文档',
  hash: '0cb71f9',
  date: '2022-10-02 10:34:31 +0800',
  timeStamp: '1664678071',
  branch: 'master'
}

`getGitLastTag()`

描述：获取最新tag

参数：

返回: string

`getGitCommitsBeforeTag(tag)`

描述：获取tag到head的提交数目

参数：

参数名	类型	描述
tag	`string`	git标签

返回: string

tag至今的提交数目

示例

getGitCommitsBeforeTag('v1.0.0');
// '12'

// 指定仓库路径
getGitCommitsBeforeTag('v1.0.0', '/path/to/repo');

`getGitAuthor(isPriorGit)`

描述：获取当前用户

参数：

参数名	描述
isPriorGit	是否优先使用git用户信息

返回: user

示例

// 默认优先 process.env.VUE_APP_AUTHOR，其次 git config user.name
getGitAuthor();
// 'novlan1'

// 优先使用 git 配置中的 user.name
getGitAuthor(true);

`reCloneGitRemote(list)`

描述：根据配置表，重新 clone 仓库

参数：

参数名	类型	描述
list	`Array<item>`	列表
item.root	`string`	路径
item.origin	`string`	origin

示例

reCloneGitRemote([
  {
    root: '/Users/foo/Documents/git/t-comm',
    origin: 'https://github.com/novlan1/t-comm',
  },
  {
    root: '/Users/foo/Documents/git/api',
    origin: 'git@git.woa.com:pmd-mobile/pmd-h5/api.git',
  },
]);
// 会先 rm -rf 目标目录，再用 ssh 协议重新 clone

引入 ​

IGitFullInfo ​

iGitFullInfo.project : string | null ​

iGitFullInfo.remoteUrl : string | null ​

iGitFullInfo.branch : string | null ​

iGitFullInfo.commitSha : string | null ​

iGitFullInfo.authorName : string | null ​

iGitFullInfo.authorEmail : string | null ​

iGitFullInfo.userName : string | null ​

iGitFullInfo.userEmail : string | null ​

iGitFullInfo.userScope : &#x27;local&#x27; | &#x27;global&#x27; | &#x27;none&#x27; ​

getAllGitRepo(root) ​

execAsync() ​

checkSingleRepo(subDir, chalk) ​

checkGitClean(dir) ​

checkGitCleanSync(dir) ​

parseConfigWithOrigin() ​

parseGitProject() ​

getGitFullInfo(root) ​

isInGitRepo(root) ​

getGitCurBranch() ​

getGitCommitMessage(root, mergeCommit, splitMessage) ​

getGitCommitInfo(root, mergeCommit, splitMessage) ​

getGitLastTag() ​

getGitCommitsBeforeTag(tag) ​

getGitAuthor(isPriorGit) ​

reCloneGitRemote(list) ​

引入

`IGitFullInfo`

`iGitFullInfo.project` : `string` | `null`

`iGitFullInfo.remoteUrl` : `string` | `null`

`iGitFullInfo.branch` : `string` | `null`

`iGitFullInfo.commitSha` : `string` | `null`

`iGitFullInfo.authorName` : `string` | `null`

`iGitFullInfo.authorEmail` : `string` | `null`

`iGitFullInfo.userName` : `string` | `null`

`iGitFullInfo.userEmail` : `string` | `null`

`iGitFullInfo.userScope` : `'local'` | `'global'` | `'none'`

`getAllGitRepo(root)`

`execAsync()`

`checkSingleRepo(subDir, chalk)`

`checkGitClean(dir)`

`checkGitCleanSync(dir)`

`parseConfigWithOrigin()`

`parseGitProject()`

`getGitFullInfo(root)`

`isInGitRepo(root)`

`getGitCurBranch()`

`getGitCommitMessage(root, mergeCommit, splitMessage)`

`getGitCommitInfo(root, mergeCommit, splitMessage)`

`getGitLastTag()`

`getGitCommitsBeforeTag(tag)`

`getGitAuthor(isPriorGit)`

`reCloneGitRemote(list)`