devel.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

To use this module, you need to import it first: import("devel.git")

git.clone

• Clone repository

Function Prototype

API

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

Parameter Description

Parameter	Description
url	Required. Git repository URL
opt	Optional. Option parameters, supports the following: - depth - Shallow clone depth - branch - Specify branch - outputdir - Output directory - recursive - Recursively clone submodules - longpaths - Enable long path support - treeless - Use tree filter - autocrlf - Auto convert line endings - fsmonitor - Enable filesystem monitoring - checkout - Whether to perform checkout

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git clone command, supporting options like shallow cloning, branch selection, and submodule handling.

import("devel.git")

-- Basic clone
git.clone("git@github.com:xmake-io/xmake.git")

-- Clone with options
git.clone("git@github.com: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

Function Prototype

API

git.init(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git init command, used to create a new git repository in the current directory or specified directory.

import("devel.git")

-- Initialize in current directory
git.init()

-- Initialize in specified directory
git.init({repodir = "/tmp/new_project"})

git.pull

• Pull latest commits from remote repository

Function Prototype

API

git.pull(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - remote - Remote repository name - branch - Branch name - tags - Whether to pull tags - force - Whether to force pull - repodir - Repository directory - fsmonitor - Enable filesystem monitoring

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git pull command, supporting options for specifying remote repository, branch, and tags.

import("devel.git")

-- Basic pull
git.pull()

-- 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.push

• Push to remote repository

Function Prototype

API

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

Parameter Description

Parameter	Description
remote	Required. Remote repository URL
opt	Optional. Option parameters, supports the following: - branch - Local branch - remote_branch - Remote branch - force - Whether to force push - repodir - Repository directory - verbose - Whether to output verbosely

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git push command, supporting force push and specifying remote branches.

import("devel.git")

-- 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

• Checkout specified branch or commit

Function Prototype

API

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

Parameter Description

Parameter	Description
ref	Required. Branch name, tag or commit hash
opt	Optional. Option parameters, supports the following: - repodir - Repository directory

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git checkout command, used to switch branches or checkout specific commits.

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

Function Prototype

API

git.reset(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory - hard - Whether to hard reset - soft - Whether to soft reset - commit - Reset to specified commit

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git reset command, supporting soft reset, hard reset and other options.

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

Function Prototype

API

git.clean(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory - force - Whether to force delete - all - Whether to delete all untracked files

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git clean command, used to remove untracked files and directories.

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

Function Prototype

API

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

Parameter Description

Parameter	Description
patch	Required. Patch file path
opt	Optional. Option parameters, supports the following: - repodir - Repository directory - reverse - Whether to apply in reverse - gitdir - Git directory

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git apply command, used to apply diff format patch files.

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

Function Prototype

API

git.branch(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory

Return Value

Type	Description
string	Returns current branch name

Usage

This interface corresponds to the git branch --show-current command, returns the name of the current branch.

import("devel.git")

-- Get current branch
local branch = git.branch({repodir = "/tmp/xmake"})
print("Current branch:", branch)

git.lastcommit

• Get latest commit hash

Function Prototype

API

git.lastcommit(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory

Return Value

Type	Description
string	Returns latest commit hash

Usage

This interface corresponds to the git rev-parse HEAD command, returns the latest commit hash of the repository.

import("devel.git")

-- Get latest commit hash
local commit = git.lastcommit({repodir = "/tmp/xmake"})
print("Last commit:", commit)

git.refs

• Get all reference list

Function Prototype

API

git.refs(url: <string>)

Parameter Description

Parameter	Description
url	Required. Remote repository URL

Return Value

Type	Description
table	Returns reference list array

Usage

This interface corresponds to the git ls-remote --refs command, returns all references of the remote repository.

import("devel.git")

-- 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 all tag list

Function Prototype

API

git.tags(url: <string>)

Parameter Description

Parameter	Description
url	Required. Remote repository URL

Return Value

Type	Description
table	Returns tag list array

Usage

This interface corresponds to the git ls-remote --tags command, returns all tags of the remote repository.

import("devel.git")

-- 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 all branch list

Function Prototype

API

git.branches(url: <string>)

Parameter Description

Parameter	Description
url	Required. Remote repository URL

Return Value

Type	Description
table	Returns branch list array

Usage

This interface corresponds to the git ls-remote --heads command, returns all branches of the remote repository.

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

• Get remote reference information

Function Prototype

API

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

Parameter Description

Parameter	Description
refs	Required. Reference type, e.g., "tags", "heads", "refs"
url	Required. Remote repository URL

Return Value

Type	Description
table	Returns reference list array

Usage

This interface corresponds to the git ls-remote command, supports getting tags, branches or all references.

import("devel.git")

-- 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

Function Prototype

API

git.checkurl(url: <string>)

Parameter Description

Parameter	Description
url	Required. URL to check

Return Value

Type	Description
boolean	Returns true if it's a git URL, false otherwise

Usage

Check if the given URL is a valid git repository address.

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

Function Prototype

API

git.asgiturl(url: <string>)

Parameter Description

Parameter	Description
url	Required. URL to convert

Return Value

Type	Description
string	Returns standard git URL format

Usage

Convert various formats of URLs to standard git URL format, supporting custom protocols.

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

Function Prototype

API

submodule.update(opt: <table>)

Parameter Description

Parameter

Description

opt

Optional. Option parameters, supports the following: - repodir - Repository directory - init - Whether to initialize submodules - remote - Whether to update remote information - recursive - Whether to recursively update - force - Whether to force update - checkout - Whether to checkout submodules - merge - Whether to merge mode - rebase - Whether to rebase mode - reference - Reference repository - paths - Specify submodule paths - longpaths - Enable long path support

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git submodule update command, used to update repository submodules.

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

Function Prototype

API

submodule.clean(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory - force - Whether to force delete - all - Whether to delete all untracked files

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git submodule foreach git clean command, used to clean untracked files in all submodules.

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

Function Prototype

API

submodule.reset(opt: <table>)

Parameter Description

Parameter	Description
opt	Optional. Option parameters, supports the following: - repodir - Repository directory - hard - Whether to hard reset - soft - Whether to soft reset - commit - Reset to specified commit - longpaths - Enable long path support

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

This interface corresponds to the git submodule foreach git reset command, used to reset the state of all submodules.

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
})