Skip to content

Git Module

The git module provides a fluent API to interact with Git repositories, allowing you to automate common version control operations like cloning, committing, and pushing.

git.clone(url, path)

Clones a Git repository to a local path.

  • Parameters:
    • url (string): The URL of the repository to clone.
    • path (string): The local directory to clone into.
  • Returns:
    • repo (object): A GitRepo object on success.
    • error: An error object if the clone fails.

git.repo(path)

Opens an existing local Git repository.

  • Parameters:
    • path (string): The path to the existing local repository.
  • Returns:
    • repo (object): A GitRepo object on success.
    • error: An error object if the path is not a valid Git repository.

The GitRepo Object

This object represents a local repository and provides chainable methods for performing Git operations.

repo:checkout(ref)

Checks out a specific branch, tag, or commit.

  • Parameters: ref (string).

repo:pull(remote, branch)

Pulls changes from a remote.

  • Parameters: remote (string), branch (string).

repo:add(pattern)

Stages files for a commit.

  • Parameters: pattern (string), e.g., "." or "path/to/file.txt".

repo:commit(message)

Creates a commit.

  • Parameters: message (string).

repo:tag(name, [message])

Creates a new tag.

  • Parameters: name (string), message (string, optional).

repo:push(remote, branch, [options])

Pushes commits to a remote.

  • Parameters:
    • remote (string).
    • branch (string).
    • options (table, optional): e.g., { follow_tags = true }.

repo:result()

This method is called at the end of a chain to get the result of the last operation.

  • Returns:
    • result (table): A table containing success (boolean), stdout (string), and stderr (string).

Example

This example demonstrates a full CI/CD-like workflow: clone, create a version file, add, commit, tag, and push.

task("git-version-bump")
  :description("Clone repository, bump version, commit, tag and push")
  :command(function(this, params)
    local git = require("git")
    local repo_path = "/tmp/git-example-repo"

    -- Clean up previous runs
    fs.rm_r(repo_path)

    -- 1. Clone the repository
    log.info("Cloning repository...")
    local repo, err = git.clone("https://github.com/chalkan3-sloth/sloth-runner.git", repo_path)
    if err then
      return false, "Failed to clone: " .. err
    end

    -- 2. Create and write a version file
    fs.write(repo_path .. "/VERSION", "1.2.3")

    -- 3. Chain Git commands: add -> commit -> tag -> push
    log.info("Adding, committing, tagging, and pushing...")
    repo:add("."):commit("ci: Bump version to 1.2.3"):tag("v1.2.3"):push("origin", "main", { follow_tags = true })

    -- 4. Get the result of the final operation (push)
    local result = repo:result()

    if not result.success then
      log.error("Git push failed: " .. result.stderr)
      return false, "Git push failed"
    end

    log.info("Successfully pushed new version tag.")
    return true, "Git operations successful"
  end)
  :build()