update git docs

docs/api/scripts/extension-modules/devel/git.md

@@ -1,92 +1,385 @@
-
 # devel.git
 
-This interface provides access to various commands of git. Compared to the direct call to git command, this module provides a more easy-to-use package interface and provides automatic detection and cross-platform processing for git.
+This interface provides access to various git commands. Compared to directly calling git commands, this module provides more high-level and easy-to-use encapsulated interfaces, and provides automatic git detection and cross-platform processing. This is an extension module of xmake.
+
+::: tip Tip
+To use this module, you need to import it first: `import("devel.git")`
+:::
 
 ## git.clone
 
-- clone codebase
+- Clone repository
 
-This interface corresponds to the `git clone` command.
+This interface corresponds to the `git clone` command, supporting options like shallow cloning, branch selection, and submodule handling.
 
 ```lua
 import("devel.git")
 
-git.clone("[email protected]:tboox/xmake.git")
-git.clone("[email protected]:tboox/xmake.git", {depth = 1, branch = "master", outputdir = "/tmp/xmake"})
+-- Basic clone
+git.clone("[email protected]:xmake-io/xmake.git")
+
+-- Clone with options
+git.clone("[email protected]:xmake-io/xmake.git", {
+    depth = 1,                    -- Shallow clone depth
+    branch = "master",            -- Specify branch
+    outputdir = "/tmp/xmake",     -- Output directory
+    recursive = true,             -- Recursively clone submodules
+    longpaths = true,             -- Enable long path support (Windows)
+    treeless = true,              -- Use tree filter (Git 2.16+)
+    autocrlf = true,              -- Auto convert line endings
+    fsmonitor = true,             -- Enable filesystem monitoring
+    checkout = false              -- Don't perform checkout
+})
+```
+
+## git.init
+
+- Initialize git repository
+
+This interface corresponds to the `git init` command, used to create a new git repository in the current directory or specified directory.
+
+```lua
+import("devel.git")
+
+-- Initialize in current directory
+git.init()
+
+-- Initialize in specified directory
+git.init({repodir = "/tmp/new_project"})
 ```
 
 ## git.pull
 
-- Pull the code base for the latest submission
+- Pull latest commits from remote repository
 
-This interface corresponds to the `git pull` command.
+This interface corresponds to the `git pull` command, supporting options for specifying remote repository, branch, and tags.
 
 ```lua
 import("devel.git")
 
+-- Basic pull
 git.pull()
-git.pull({remote = "origin", tags = true, branch = "master", repodir = "/tmp/xmake"})
+
+-- Pull with options
+git.pull({
+    remote = "origin",            -- Remote repository name
+    branch = "master",            -- Branch name
+    tags = true,                  -- Pull tags
+    force = true,                 -- Force pull
+    repodir = "/tmp/xmake",       -- Repository directory
+    fsmonitor = true              -- Enable filesystem monitoring
+})
 ```
 
-## git.clean
+## git.push
 
-- Clean up the code base file
+- Push to remote repository
 
-This interface corresponds to the `git clean` command.
+This interface corresponds to the `git push` command, supporting force push and specifying remote branches.
 
 ```lua
 import("devel.git")
 
-git.clean()
-git.clean({repodir = "/tmp/xmake", force = true})
+-- Push to remote repository
+git.push("https://github.com/user/repo.git", {
+    branch = "master",            -- Local branch
+    remote_branch = "main",       -- Remote branch
+    force = true,                 -- Force push
+    repodir = "/tmp/xmake",       -- Repository directory
+    verbose = true                -- Verbose output
+})
 ```
 
 ## git.checkout
 
-- Check out the specified branch version
+- Checkout specified branch or commit
 
-This interface corresponds to the `git checkout` command
+This interface corresponds to the `git checkout` command, used to switch branches or checkout specific commits.
 
 ```lua
 import("devel.git")
 
+-- Switch to branch
 git.checkout("master", {repodir = "/tmp/xmake"})
+
+-- Checkout tag
 git.checkout("v1.0.1", {repodir = "/tmp/xmake"})
+
+-- Checkout commit
+git.checkout("abc1234", {repodir = "/tmp/xmake"})
+```
+
+## git.reset
+
+- Reset repository state
+
+This interface corresponds to the `git reset` command, supporting soft reset, hard reset and other options.
+
+```lua
+import("devel.git")
+
+-- Basic reset
+git.reset({repodir = "/tmp/xmake"})
+
+-- Hard reset to specified commit
+git.reset({
+    repodir = "/tmp/xmake",
+    hard = true,                  -- Hard reset
+    commit = "HEAD~1"             -- Reset to previous commit
+})
+
+-- Soft reset
+git.reset({
+    repodir = "/tmp/xmake",
+    soft = true,                  -- Soft reset
+    commit = "abc1234"            -- Reset to specified commit
+})
+```
+
+## git.clean
+
+- Clean working directory
+
+This interface corresponds to the `git clean` command, used to remove untracked files and directories.
+
+```lua
+import("devel.git")
+
+-- Basic clean
+git.clean({repodir = "/tmp/xmake"})
+
+-- Force clean
+git.clean({
+    repodir = "/tmp/xmake",
+    force = true,                 -- Force delete
+    all = true                    -- Delete all untracked files
+})
+```
+
+## git.apply
+
+- Apply patch file
+
+This interface corresponds to the `git apply` command, used to apply diff format patch files.
+
+```lua
+import("devel.git")
+
+-- Apply patch
+git.apply("fix.patch", {
+    repodir = "/tmp/xmake",
+    reverse = true,               -- Apply patch in reverse
+    gitdir = ".git"               -- Specify git directory
+})
+
+-- Apply diff file
+git.apply("changes.diff")
+```
+
+## git.branch
+
+- Get current branch name
+
+This interface corresponds to the `git branch --show-current` command, returns the name of the current branch.
+
+```lua
+import("devel.git")
+
+-- Get current branch
+local branch = git.branch({repodir = "/tmp/xmake"})
+print("Current branch:", branch)
+```
+
+## git.lastcommit
+
+- Get latest commit hash
+
+This interface corresponds to the `git rev-parse HEAD` command, returns the latest commit hash of the repository.
+
+```lua
+import("devel.git")
+
+-- Get latest commit hash
+local commit = git.lastcommit({repodir = "/tmp/xmake"})
+print("Last commit:", commit)
 ```
 
 ## git.refs
 
-- Get a list of all references
+- Get all reference list
 
-This interface corresponds to the `git ls-remote --refs` command
+This interface corresponds to the `git ls-remote --refs` command, returns all references of the remote repository.
 
 ```lua
 import("devel.git")
 
-local refs = git.refs(url)
+-- Get all references
+local refs = git.refs("https://github.com/xmake-io/xmake.git")
+for _, ref in ipairs(refs) do
+    print("Ref:", ref)
+end
 ```
 
 ## git.tags
 
-- Get a list of all tags
+- Get all tag list
 
-This interface corresponds to the `git ls-remote --tags` command
+This interface corresponds to the `git ls-remote --tags` command, returns all tags of the remote repository.
 
 ```lua
 import("devel.git")
 
-local tags = git.tags(url)
+-- Get all tags
+local tags = git.tags("https://github.com/xmake-io/xmake.git")
+for _, tag in ipairs(tags) do
+    print("Tag:", tag)
+end
 ```
 
 ## git.branches
 
-- Get a list of all branches
+- Get all branch list
+
+This interface corresponds to the `git ls-remote --heads` command, returns all branches of the remote repository.
+
+```lua
+import("devel.git")
+
+-- Get all branches
+local branches = git.branches("https://github.com/xmake-io/xmake.git")
+for _, branch in ipairs(branches) do
+    print("Branch:", branch)
+end
+```
+
+## git.ls_remote
 
-This interface corresponds to the `git ls-remote --heads` command
+- Get remote reference information
+
+This interface corresponds to the `git ls-remote` command, supports getting tags, branches or all references.
 
 ```lua
 import("devel.git")
 
-local branches = git.branches(url)
+-- Get tags
+local tags = git.ls_remote("tags", "https://github.com/xmake-io/xmake.git")
+
+-- Get branches
+local heads = git.ls_remote("heads", "https://github.com/xmake-io/xmake.git")
+
+-- Get all references
+local refs = git.ls_remote("refs")
 ```
+
+## git.checkurl
+
+- Check if it's a git URL
+
+Check if the given URL is a valid git repository address.
+
+```lua
+import("devel.git")
+
+-- Check 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
+
+- Convert URL to git format
+
+Convert various formats of URLs to standard git URL format, supporting custom protocols.
+
+```lua
+import("devel.git")
+
+-- Convert URL to git format
+local git_url = git.asgiturl("github:xmake-io/xmake")
+print("Git URL:", git_url)  -- https://github.com/xmake-io/xmake.git
+
+-- Supported custom protocols
+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
+
+- Update submodules
+
+This interface corresponds to the `git submodule update` command, used to update repository submodules.
+
+```lua
+import("devel.git.submodule")
+
+-- Basic update
+submodule.update({repodir = "/tmp/xmake"})
+
+-- Update with options
+submodule.update({
+    repodir = "/tmp/xmake",
+    init = true,                 -- Initialize submodules
+    remote = true,               -- Update remote information
+    recursive = true,            -- Recursive update
+    force = true,                -- Force update
+    checkout = true,             -- Checkout submodules
+    merge = true,                -- Merge mode
+    rebase = true,               -- Rebase mode
+    reference = "/path/to/repo", -- Reference repository
+    paths = {"submodule1", "submodule2"}, -- Specify submodule paths
+    longpaths = true             -- Enable long path support
+})
+```
+
+## submodule.clean
+
+- Clean submodules
+
+This interface corresponds to the `git submodule foreach git clean` command, used to clean untracked files in all submodules.
+
+```lua
+import("devel.git.submodule")
+
+-- Basic clean
+submodule.clean({repodir = "/tmp/xmake"})
+
+-- Force clean
+submodule.clean({
+    repodir = "/tmp/xmake",
+    force = true,                 -- Force delete
+    all = true                    -- Delete all untracked files
+})
+```
+
+## submodule.reset
+
+- Reset submodules
+
+This interface corresponds to the `git submodule foreach git reset` command, used to reset the state of all submodules.
+
+```lua
+import("devel.git.submodule")
+
+-- Basic reset
+submodule.reset({repodir = "/tmp/xmake"})
+
+-- Hard reset
+submodule.reset({
+    repodir = "/tmp/xmake",
+    hard = true,                  -- Hard reset
+    commit = "HEAD"               -- Reset to specified commit
+})
+
+-- Soft reset
+submodule.reset({
+    repodir = "/tmp/xmake",
+    soft = true,                  -- Soft reset
+    longpaths = true              -- Enable long path support
+})
+```

docs/zh/api/scripts/extension-modules/devel/git.md

@@ -1,92 +1,386 @@
 
 # devel.git
 
-此接口提供了git各种命令的访问接口，相对于直接调用git命令，此模块提供了更加上层易用的封装接口，并且提供对git的自动检测和跨平台处理。
+此接口提供了git各种命令的访问接口，相对于直接调用git命令，此模块提供了更加上层易用的封装接口，并且提供对git的自动检测和跨平台处理。这是 xmake 的扩展模块。
+
+::: tip 提示
+使用此模块需要先导入：`import("devel.git")`
+:::
 
 ## git.clone
 
-- clone代码库
+- 克隆代码库
 
-此接口对应`git clone`命令
+此接口对应`git clone`命令，支持深度克隆、分支选择、子模块处理等选项。
 
 ```lua
 import("devel.git")
 
-git.clone("[email protected]:tboox/xmake.git")
-git.clone("[email protected]:tboox/xmake.git", {depth = 1, branch = "master", outputdir = "/tmp/xmake"})
+-- 基本克隆
+git.clone("[email protected]:xmake-io/xmake.git")
+
+-- 带选项的克隆
+git.clone("[email protected]: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仓库
+
+此接口对应`git init`命令，用于在当前目录或指定目录创建新的git仓库。
+
+```lua
+import("devel.git")
+
+-- 在当前目录初始化
+git.init()
+
+-- 在指定目录初始化
+git.init({repodir = "/tmp/new_project"})
 ```
 
 ## git.pull
 
-- 拉取代码库最新提交
+- 拉取远程仓库最新提交
 
-此接口对应`git pull`命令
+此接口对应`git pull`命令，支持指定远程仓库、分支和标签选项。
 
 ```lua
 import("devel.git")
 
+-- 基本拉取
 git.pull()
-git.pull({remote = "origin", tags = true, branch = "master", repodir = "/tmp/xmake"})
+
+-- 带选项的拉取
+git.pull({
+    remote = "origin",            -- 远程仓库名
+    branch = "master",            -- 分支名
+    tags = true,                  -- 拉取标签
+    force = true,                 -- 强制拉取
+    repodir = "/tmp/xmake",       -- 仓库目录
+    fsmonitor = true              -- 启用文件系统监控
+})
 ```
 
-## git.clean
+## git.push
 
-- 清理代码库文件
+- 推送到远程仓库
 
-此接口对应`git clean`命令
+此接口对应`git push`命令，支持强制推送和指定远程分支。
 
 ```lua
 import("devel.git")
 
-git.clean()
-git.clean({repodir = "/tmp/xmake", force = true})
+-- 推送到远程仓库
+git.push("https://github.com/user/repo.git", {
+    branch = "master",            -- 本地分支
+    remote_branch = "main",       -- 远程分支
+    force = true,                 -- 强制推送
+    repodir = "/tmp/xmake",       -- 仓库目录
+    verbose = true                -- 详细输出
+})
 ```
 
 ## git.checkout
 
-- 签出指定分支版本
+- 签出指定分支或提交
 
-此接口对应`git checkout`命令
+此接口对应`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
+
+- 重置仓库状态
+
+此接口对应`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
+
+- 清理工作目录
+
+此接口对应`git clean`命令，用于移除未跟踪的文件和目录。
+
+```lua
+import("devel.git")
+
+-- 基本清理
+git.clean({repodir = "/tmp/xmake"})
+
+-- 强制清理
+git.clean({
+    repodir = "/tmp/xmake",
+    force = true,                 -- 强制删除
+    all = true                    -- 删除所有未跟踪文件
+})
+```
+
+## git.apply
+
+- 应用补丁文件
+
+此接口对应`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
+
+- 获取当前分支名
+
+此接口对应`git branch --show-current`命令，返回当前所在分支的名称。
+
+```lua
+import("devel.git")
+
+-- 获取当前分支
+local branch = git.branch({repodir = "/tmp/xmake"})
+print("Current branch:", branch)
+```
+
+## git.lastcommit
+
+- 获取最新提交哈希
+
+此接口对应`git rev-parse HEAD`命令，返回仓库的最新提交哈希值。
+
+```lua
+import("devel.git")
+
+-- 获取最新提交哈希
+local commit = git.lastcommit({repodir = "/tmp/xmake"})
+print("Last commit:", commit)
 ```
 
 ## git.refs
 
 - 获取所有引用列表
 
-此接口对应`git ls-remote --refs`命令
+此接口对应`git ls-remote --refs`命令，返回远程仓库的所有引用。
 
 ```lua
 import("devel.git")
 
-local refs = git.refs(url)
+-- 获取所有引用
+local refs = git.refs("https://github.com/xmake-io/xmake.git")
+for _, ref in ipairs(refs) do
+    print("Ref:", ref)
+end
 ```
 
 ## git.tags
 
-- 获取所有标记列表
+- 获取所有标签列表
 
-此接口对应`git ls-remote --tags`命令
+此接口对应`git ls-remote --tags`命令，返回远程仓库的所有标签。
 
 ```lua
 import("devel.git")
 
-local tags = git.tags(url)
+-- 获取所有标签
+local tags = git.tags("https://github.com/xmake-io/xmake.git")
+for _, tag in ipairs(tags) do
+    print("Tag:", tag)
+end
 ```
 
 ## git.branches
 
 - 获取所有分支列表
 
-此接口对应`git ls-remote --heads`命令
+此接口对应`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
+
+- 获取远程引用信息
+
+此接口对应`git ls-remote`命令，支持获取标签、分支或所有引用。
 
 ```lua
 import("devel.git")
 
-local branches = git.branches(url)
+-- 获取标签
+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
+
+检查给定的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格式
+
+将各种格式的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
+
+- 更新子模块
+
+此接口对应`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
+
+- 清理子模块
+
+此接口对应`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
+
+- 重置子模块
+
+此接口对应`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              -- 启用长路径支持
+})
 ```