devel.git

此接口提供了git各种命令的访问接口，相对于直接调用git命令，此模块提供了更加上层易用的封装接口，并且提供对git的自动检测和跨平台处理。这是 xmake 的扩展模块。

提示

使用此模块需要先导入：import("devel.git")

git.clone

克隆代码库

函数原型

API

lua

git.clone(url: <string>, opt: <table>)

参数说明

参数	描述
url	必需。git仓库URL
opt	可选。选项参数，支持以下选项： - `depth` - 浅克隆深度 - `branch` - 指定分支 - `outputdir` - 输出目录 - `recursive` - 递归克隆子模块 - `longpaths` - 启用长路径支持 - `treeless` - 使用树形过滤 - `autocrlf` - 自动转换换行符 - `fsmonitor` - 启用文件系统监控 - `checkout` - 是否执行检出

返回值说明

类型	描述
boolean	克隆成功返回 true，失败返回 false

用法说明

此接口对应git clone命令，支持深度克隆、分支选择、子模块处理等选项。

lua

import("devel.git")

-- 基本克隆
git.clone("git@github.com:xmake-io/xmake.git")

-- 带选项的克隆
git.clone("git@github.com:xmake-io/xmake.git", {
    depth = 1,                    -- 浅克隆深度
    branch = "master",            -- 指定分支
    outputdir = "/tmp/xmake",     -- 输出目录
    recursive = true,             -- 递归克隆子模块
    longpaths = true,             -- 启用长路径支持（Windows）
    treeless = true,              -- 使用树形过滤（Git 2.16+）
    autocrlf = true,              -- 自动转换换行符
    fsmonitor = true,             -- 启用文件系统监控
    checkout = false              -- 不执行检出
})

git.init

初始化git仓库

函数原型

API

lua

git.init(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录

返回值说明

类型	描述
boolean	初始化成功返回 true，失败返回 false

用法说明

此接口对应git init命令，用于在当前目录或指定目录创建新的git仓库。

lua

import("devel.git")

-- 在当前目录初始化
git.init()

-- 在指定目录初始化
git.init({repodir = "/tmp/new_project"})

git.pull

拉取远程仓库最新提交

函数原型

API

lua

git.pull(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `remote` - 远程仓库名 - `branch` - 分支名 - `tags` - 是否拉取标签 - `force` - 是否强制拉取 - `repodir` - 仓库目录 - `fsmonitor` - 启用文件系统监控

返回值说明

类型	描述
boolean	拉取成功返回 true，失败返回 false

用法说明

此接口对应git pull命令，支持指定远程仓库、分支和标签选项。

lua

import("devel.git")

-- 基本拉取
git.pull()

-- 带选项的拉取
git.pull({
    remote = "origin",            -- 远程仓库名
    branch = "master",            -- 分支名
    tags = true,                  -- 拉取标签
    force = true,                 -- 强制拉取
    repodir = "/tmp/xmake",       -- 仓库目录
    fsmonitor = true              -- 启用文件系统监控
})

git.push

推送到远程仓库

函数原型

API

lua

git.push(remote: <string>, opt: <table>)

参数说明

参数	描述
remote	必需。远程仓库URL
opt	可选。选项参数，支持以下选项： - `branch` - 本地分支 - `remote_branch` - 远程分支 - `force` - 是否强制推送 - `repodir` - 仓库目录 - `verbose` - 是否详细输出

返回值说明

类型	描述
boolean	推送成功返回 true，失败返回 false

用法说明

此接口对应git push命令，支持强制推送和指定远程分支。

lua

import("devel.git")

-- 推送到远程仓库
git.push("https://github.com/user/repo.git", {
    branch = "master",            -- 本地分支
    remote_branch = "main",       -- 远程分支
    force = true,                 -- 强制推送
    repodir = "/tmp/xmake",       -- 仓库目录
    verbose = true                -- 详细输出
})

git.checkout

签出指定分支或提交

函数原型

API

lua

git.checkout(ref: <string>, opt: <table>)

参数说明

参数	描述
ref	必需。分支名、标签或提交哈希
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录

返回值说明

类型	描述
boolean	签出成功返回 true，失败返回 false

用法说明

此接口对应git checkout命令，用于切换分支或检出特定提交。

lua

import("devel.git")

-- 切换到分支
git.checkout("master", {repodir = "/tmp/xmake"})

-- 检出标签
git.checkout("v1.0.1", {repodir = "/tmp/xmake"})

-- 检出提交
git.checkout("abc1234", {repodir = "/tmp/xmake"})

git.reset

重置仓库状态

函数原型

API

lua

git.reset(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `hard` - 是否硬重置 - `soft` - 是否软重置 - `commit` - 重置到指定提交

返回值说明

类型	描述
boolean	重置成功返回 true，失败返回 false

用法说明

此接口对应git reset命令，支持软重置、硬重置等选项。

lua

import("devel.git")

-- 基本重置
git.reset({repodir = "/tmp/xmake"})

-- 硬重置到指定提交
git.reset({
    repodir = "/tmp/xmake",
    hard = true,                  -- 硬重置
    commit = "HEAD~1"             -- 重置到上一个提交
})

-- 软重置
git.reset({
    repodir = "/tmp/xmake",
    soft = true,                  -- 软重置
    commit = "abc1234"            -- 重置到指定提交
})

git.clean

函数原型

API

lua

git.clean(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `force` - 是否强制删除 - `all` - 是否删除所有未跟踪文件

返回值说明

类型	描述
boolean	清理成功返回 true，失败返回 false

用法说明

此接口对应git clean命令，用于移除未跟踪的文件和目录。

lua

import("devel.git")

-- 基本清理
git.clean({repodir = "/tmp/xmake"})

-- 强制清理
git.clean({
    repodir = "/tmp/xmake",
    force = true,                 -- 强制删除
    all = true                    -- 删除所有未跟踪文件
})

git.apply

应用补丁文件

函数原型

API

lua

git.apply(patch: <string>, opt: <table>)

参数说明

参数	描述
patch	必需。补丁文件路径
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `reverse` - 是否反向应用 - `gitdir` - git目录

返回值说明

类型	描述
boolean	应用成功返回 true，失败返回 false

用法说明

此接口对应git apply命令，用于应用diff格式的补丁文件。

lua

import("devel.git")

-- 应用补丁
git.apply("fix.patch", {
    repodir = "/tmp/xmake",
    reverse = true,               -- 反向应用补丁
    gitdir = ".git"               -- 指定git目录
})

-- 应用diff文件
git.apply("changes.diff")

git.branch

获取当前分支名

函数原型

API

lua

git.branch(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录

返回值说明

类型	描述
string	返回当前分支名

用法说明

此接口对应git branch --show-current命令，返回当前所在分支的名称。

lua

import("devel.git")

-- 获取当前分支
local branch = git.branch({repodir = "/tmp/xmake"})
print("Current branch:", branch)

git.lastcommit

获取最新提交哈希

函数原型

API

lua

git.lastcommit(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录

返回值说明

类型	描述
string	返回最新提交哈希

用法说明

此接口对应git rev-parse HEAD命令，返回仓库的最新提交哈希值。

lua

import("devel.git")

-- 获取最新提交哈希
local commit = git.lastcommit({repodir = "/tmp/xmake"})
print("Last commit:", commit)

git.refs

获取所有引用列表

函数原型

API

lua

git.refs(url: <string>)

参数说明

参数	描述
url	必需。远程仓库URL

返回值说明

类型	描述
table	返回引用列表数组

用法说明

此接口对应git ls-remote --refs命令，返回远程仓库的所有引用。

lua

import("devel.git")

-- 获取所有引用
local refs = git.refs("https://github.com/xmake-io/xmake.git")
for _, ref in ipairs(refs) do
    print("Ref:", ref)
end

git.tags

获取所有标签列表

函数原型

API

lua

git.tags(url: <string>)

参数说明

参数	描述
url	必需。远程仓库URL

返回值说明

类型	描述
table	返回标签列表数组

用法说明

此接口对应git ls-remote --tags命令，返回远程仓库的所有标签。

lua

import("devel.git")

-- 获取所有标签
local tags = git.tags("https://github.com/xmake-io/xmake.git")
for _, tag in ipairs(tags) do
    print("Tag:", tag)
end

git.branches

获取所有分支列表

函数原型

API

lua

git.branches(url: <string>)

参数说明

参数	描述
url	必需。远程仓库URL

返回值说明

类型	描述
table	返回分支列表数组

用法说明

此接口对应git ls-remote --heads命令，返回远程仓库的所有分支。

lua

import("devel.git")

-- 获取所有分支
local branches = git.branches("https://github.com/xmake-io/xmake.git")
for _, branch in ipairs(branches) do
    print("Branch:", branch)
end

git.ls_remote

获取远程引用信息

函数原型

API

lua

git.ls_remote(refs: <string>, url: <string>)

参数说明

参数	描述
refs	必需。引用类型，例如 "tags", "heads", "refs"
url	必需。远程仓库URL

返回值说明

类型	描述
table	返回引用列表数组

用法说明

此接口对应git ls-remote命令，支持获取标签、分支或所有引用。

lua

import("devel.git")

-- 获取标签
local tags = git.ls_remote("tags", "https://github.com/xmake-io/xmake.git")

-- 获取分支
local heads = git.ls_remote("heads", "https://github.com/xmake-io/xmake.git")

-- 获取所有引用
local refs = git.ls_remote("refs")

git.checkurl

检查是否为git URL

函数原型

API

lua

git.checkurl(url: <string>)

参数说明

参数	描述
url	必需。要检查的URL

返回值说明

类型	描述
boolean	是git URL返回 true，否则返回 false

用法说明

检查给定的URL是否为有效的git仓库地址。

lua

import("devel.git")

-- 检查URL
local is_git = git.checkurl("https://github.com/xmake-io/xmake.git")
if is_git then
    print("This is a git URL")
end

git.asgiturl

转换URL为git格式

函数原型

API

lua

git.asgiturl(url: <string>)

参数说明

参数	描述
url	必需。要转换的URL

返回值说明

类型	描述
string	返回标准git URL格式

用法说明

将各种格式的URL转换为标准的git URL格式，支持自定义协议。

lua

import("devel.git")

-- 转换URL为git格式
local git_url = git.asgiturl("github:xmake-io/xmake")
print("Git URL:", git_url)  -- https://github.com/xmake-io/xmake.git

-- 支持的自定义协议
local protocols = {
    "github:user/repo",      -- https://github.com/user/repo.git
    "gitlab:user/repo",      -- https://gitlab.com/user/repo.git
    "gitee:user/repo",       -- https://gitee.com/user/repo.git
    "bitbucket:user/repo"    -- https://bitbucket.org/user/repo.git
}

submodule.update

更新子模块

函数原型

API

lua

submodule.update(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `init` - 是否初始化子模块 - `remote` - 是否更新远程信息 - `recursive` - 是否递归更新 - `force` - 是否强制更新 - `checkout` - 是否检出子模块 - `merge` - 是否合并模式 - `rebase` - 是否变基模式 - `reference` - 引用仓库 - `paths` - 指定子模块路径 - `longpaths` - 启用长路径支持

返回值说明

类型	描述
boolean	更新成功返回 true，失败返回 false

用法说明

此接口对应git submodule update命令，用于更新仓库的子模块。

lua

import("devel.git.submodule")

-- 基本更新
submodule.update({repodir = "/tmp/xmake"})

-- 带选项的更新
submodule.update({
    repodir = "/tmp/xmake",
    init = true,                 -- 初始化子模块
    remote = true,               -- 更新远程信息
    recursive = true,            -- 递归更新
    force = true,                -- 强制更新
    checkout = true,             -- 检出子模块
    merge = true,                -- 合并模式
    rebase = true,               -- 变基模式
    reference = "/path/to/repo", -- 引用仓库
    paths = {"submodule1", "submodule2"}, -- 指定子模块路径
    longpaths = true             -- 启用长路径支持
})

submodule.clean

清理子模块

函数原型

API

lua

submodule.clean(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `force` - 是否强制删除 - `all` - 是否删除所有未跟踪文件

返回值说明

类型	描述
boolean	清理成功返回 true，失败返回 false

用法说明

此接口对应git submodule foreach git clean命令，用于清理所有子模块的未跟踪文件。

lua

import("devel.git.submodule")

-- 基本清理
submodule.clean({repodir = "/tmp/xmake"})

-- 强制清理
submodule.clean({
    repodir = "/tmp/xmake",
    force = true,                 -- 强制删除
    all = true                    -- 删除所有未跟踪文件
})

submodule.reset

重置子模块

函数原型

API

lua

submodule.reset(opt: <table>)

参数说明

参数	描述
opt	可选。选项参数，支持以下选项： - `repodir` - 仓库目录 - `hard` - 是否硬重置 - `soft` - 是否软重置 - `commit` - 重置到指定提交 - `longpaths` - 启用长路径支持

返回值说明

类型	描述
boolean	重置成功返回 true，失败返回 false

用法说明

此接口对应git submodule foreach git reset命令，用于重置所有子模块的状态。

lua

import("devel.git.submodule")

-- 基本重置
submodule.reset({repodir = "/tmp/xmake"})

-- 硬重置
submodule.reset({
    repodir = "/tmp/xmake",
    hard = true,                  -- 硬重置
    commit = "HEAD"               -- 重置到指定提交
})

-- 软重置
submodule.reset({
    repodir = "/tmp/xmake",
    soft = true,                  -- 软重置
    longpaths = true              -- 启用长路径支持
})

devel.git ​

git.clone ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.init ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.pull ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.push ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.checkout ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.reset ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.clean ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.apply ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.branch ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.lastcommit ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.refs ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.tags ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.branches ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.ls_remote ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.checkurl ​

函数原型 ​

参数说明 ​

返回值说明 ​

用法说明 ​

git.asgiturl ​

函数原型 ​

参数说明 ​

返回值说明 ​

devel.git

git.clone

函数原型

参数说明

返回值说明

用法说明

git.init

函数原型

参数说明

返回值说明

用法说明

git.pull

函数原型

参数说明

返回值说明

用法说明

git.push

函数原型

参数说明

返回值说明

用法说明

git.checkout

函数原型

参数说明

返回值说明

用法说明

git.reset

函数原型

参数说明

返回值说明

用法说明

git.clean

函数原型

参数说明

返回值说明

用法说明

git.apply

函数原型

参数说明

返回值说明

用法说明

git.branch

函数原型

参数说明

返回值说明

用法说明

git.lastcommit

函数原型

参数说明

返回值说明

用法说明

git.refs

函数原型

参数说明

返回值说明

用法说明

git.tags

函数原型

参数说明

返回值说明

用法说明

git.branches

函数原型

参数说明

返回值说明

用法说明

git.ls_remote

函数原型

参数说明

返回值说明

用法说明

git.checkurl

函数原型

参数说明

返回值说明

用法说明

git.asgiturl

函数原型

参数说明

返回值说明