API de Git

Los ayudantes de repositorio de Git están disponibles en ptool.git y p.git.

Este módulo se basa en git2 / libgit2, no en invocar la herramienta de línea de comandos git.

ptool.git.open

Unreleased - Introducido.

ptool.git.open(path?) abre un repositorio directamente y devuelve un objeto Repo.

Argumentos:

• path (cadena, opcional): Ruta del repositorio. Si se omite, se utiliza el directorio de tiempo de ejecución ptool actual.

Comportamiento:

• Las rutas relativas se resuelven desde el directorio de tiempo de ejecución ptool actual, por lo que siguen a ptool.cd(...).
• Esto no busca directorios principales. Utilice ptool.git.discover(...) cuando desee un comportamiento de descubrimiento de repositorios.

Ejemplo:

local repo = ptool.git.open(".")
print(repo:path())

ptool.git.discover

Unreleased - Introducido.

ptool.git.discover(path?) encuentra un repositorio que comienza desde path y avanza por los directorios principales, luego devuelve un objeto Repo.

Argumentos:

• path (cadena, opcional): Ruta de inicio. Si se omite, se utiliza el directorio de tiempo de ejecución ptool actual.

Comportamiento:

• Las rutas relativas se resuelven desde el directorio de tiempo de ejecución ptool actual.
• Esto es útil cuando un script puede ejecutarse desde un subdirectorio dentro de un árbol de trabajo.

Ejemplo:

local repo = ptool.git.discover("src")
print(repo:root())

ptool.git.clone

Unreleased - Introducido.

ptool.git.clone(url, path[, options]) clona un repositorio y devuelve un objeto Repo para el repositorio clonado.

Argumentos:

• url (string, requerido): URL del repositorio remoto.
• path (string, required): Ruta de destino.
• options (tabla, opcional): Opciones de clonación. Campos admitidos:
  • branch (cadena, opcional): Nombre de la rama a hacer checkout después de clonar.
  • bare (booleano, opcional): Si se debe crear un repositorio bare. El valor predeterminado es false.
  • auth (tabla, opcional): Configuración de autenticación remota.

Campos auth:

• kind (string, required): Modo de autenticación. Valores admitidos:
  • "default": Utilice las credenciales predeterminadas de libgit2.
  • "ssh_agent": Autenticar a través del agente SSH local.
  • "userpass": Utiliza un nombre de usuario y una contraseña en texto plano.
• username (cadena, opcional): Nombre de usuario para "ssh_agent".
• username (string, requerido): Nombre de usuario para "userpass".
• password (string, requerido): Contraseña para "userpass".

Comportamiento:

• Las rutas de destino relativas se resuelven desde el directorio de tiempo de ejecución ptool actual.
• Las opciones de autenticación también son utilizadas por repo:fetch(...) y repo:push(...).

Ejemplo:

local repo = ptool.git.clone(
  "[email protected]:example/project.git",
  "tmp/project",
  {
    branch = "main",
    auth = {
      kind = "ssh_agent",
    },
  }
)

print(repo:root())

Repo

Unreleased - Introducido.

Repo representa un identificador de repositorio Git abierto devuelto por ptool.git.open(), ptool.git.discover() o ptool.git.clone().

Se implementa como datos de usuario de Lua.

Métodos:

• repo:path() -> string
• repo:root() -> string|nil
• repo:is_bare() -> boolean
• repo:head() -> table
• repo:current_branch() -> string|nil
• repo:status([options]) -> table
• repo:is_clean([options]) -> boolean
• repo:add(paths[, options]) -> nil
• repo:commit(message[, options]) -> string
• repo:checkout(rev[, options]) -> nil
• repo:switch(branch[, options]) -> nil
• repo:fetch([remote[, options]]) -> table
• repo:push([remote[, refspecs[, options]]]) -> nil

path

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:path.

repo:path() devuelve la ruta del directorio git del repositorio.

• Devuelve: string.

Notas:

• Para un repositorio no bare, normalmente este es el directorio .git.
• Para un repositorio bare, este es el propio directorio del repositorio.

root

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:root.

repo:root() devuelve el directorio raíz del árbol de trabajo.

• Devuelve: string|nil.

Notas:

• Esto devuelve nil para repositorios bare.

is_bare

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:is_bare.

repo:is_bare() informa si el repositorio es bare.

• Devuelve: boolean.

head

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:head.

repo:head() devuelve información de HEAD en una tabla con:

• oid (string|nil): El OID del commit actual, si está disponible.
• shorthand (string|nil): Un nombre corto para HEAD, como el nombre de una rama.
• detached (booleano): Si HEAD está detached.
• unborn (booleano): Si el repositorio todavía no tiene un commit inicial.

Ejemplo:

local head = repo:head()
print(head.oid)
print(head.detached)

current_branch

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:current_branch.

repo:current_branch() devuelve el nombre de la rama local actual.

• Devuelve: string|nil.

Notas:

• Esto devuelve nil cuando HEAD está detached.
• Esto también devuelve nil para una rama unborn antes del primer commit.

status

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:status.

repo:status([options]) resume el estado del repositorio y devuelve una tabla con:

• root (string|nil): El directorio raíz del árbol de trabajo.
• branch (string|nil): El nombre de la rama local actual.
• head (tabla): La misma información de HEAD devuelta por repo:head().
• upstream (string|nil): El nombre de la rama upstream, cuando está configurada.
• ahead (entero): Número de commits por delante del upstream.
• behind (entero): Número de commits por detrás del upstream.
• clean (booleano): si el repositorio no tiene entradas de estado visibles.
• entries (tabla): Una matriz de tablas de entrada de estado.

entries[i] contiene:

• path (string): Ruta relativa al repositorio.
• index_status (string|nil): Estado del lado del índice. Los valores admitidos actualmente incluyen "new", "modified", "deleted", "renamed" y "typechange".
• worktree_status (string|nil): estado del lado del árbol de trabajo. Los valores admitidos actualmente incluyen "new", "modified", "deleted", "renamed", "typechange" y "ignored".
• conflicted (booleano): si la ruta está en conflicto.
• ignored (booleano): si se ignora la ruta.

Campos options:

• include_untracked (booleano, opcional): si se deben incluir archivos no rastreados. El valor predeterminado es true.
• include_ignored (booleano, opcional): si se deben incluir archivos ignorados. El valor predeterminado es false.
• recurse_untracked_dirs (booleano, opcional): Si se recurre en directorios no rastreados. El valor predeterminado es true.

Ejemplo:

local st = repo:status()
print(st.clean)
print(st.branch)

for _, entry in ipairs(st.entries) do
  print(entry.path, entry.index_status, entry.worktree_status)
end

is_clean

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:is_clean.

repo:is_clean([options]) devuelve si el repositorio está limpio.

• options (tabla, opcional): Las mismas opciones aceptadas por repo:status(...).
• Devuelve: boolean.

add

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:add.

repo:add(paths[, options]) añade una o más rutas al índice.

Argumentos:

• paths (string|string[], requerido): Una ruta o una matriz de rutas.
• options (tabla, opcional): Añadir opciones. Campos admitidos:
  • update (booleano, opcional): Actualiza solo las rutas ya conocidas por el índice. El valor predeterminado es false.

Comportamiento:

• Las rutas se interpretan en relación con el árbol de trabajo del repositorio.

Ejemplo:

repo:add("README.md")
repo:add({"src", "Cargo.toml"})

commit

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:commit.

repo:commit(message[, options]) crea un commit a partir del índice actual y devuelve el nuevo OID del commit.

Argumentos:

• message (cadena, obligatorio): Mensaje del commit.
• options (tabla, opcional): Opciones de confirmación. Campos admitidos:
  • author (tabla, opcional): Firma del autor.
  • committer (tabla, opcional): Firma del comitente.

Campos de firma:

• name (string, requerido)
• email (string, requerido)

Comportamiento:

• Cuando se omiten author y committer, ptool intenta utilizar la identidad del repositorio Git desde la configuración.
• Si no se configura ninguna identidad y no se proporciona ninguna firma explícita, se genera un error.

Ejemplo:

local oid = repo:commit("Release v0.7.0", {
  author = {
    name = "Release Bot",
    email = "[email protected]",
  },
})

print(oid)

checkout

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:checkout.

repo:checkout(rev[, options]) hace checkout de una revisión.

Argumentos:

• rev (string, required): expresión de revisión como un nombre de rama, nombre de etiqueta u Oid de confirmación.
• options (tabla, opcional): Opciones de checkout. Campos admitidos:
  • force (booleano, opcional): Si se debe forzar el checkout. El valor predeterminado es false.

Comportamiento:

• Esto puede dejar HEAD en detached cuando rev no se resuelve a una referencia con nombre.

switch

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:switch.

repo:switch(branch[, options]) cambia HEAD a una rama local.

Argumentos:

• branch (cadena, obligatorio): Nombre de la rama local.
• options (tabla, opcional): Opciones de switch. Campos admitidos:
  • create (booleano, opcional): Si se crea primero la rama. El valor predeterminado es false.
  • force (booleano, opcional): Si forzar el pago. El valor predeterminado es false.
  • start_point (cadena, opcional): Revisión para ramificar desde cuando create = true. El valor predeterminado es HEAD.

Ejemplo:

repo:switch("release")
repo:switch("release-next", {
  create = true,
  start_point = "origin/main",
})

fetch

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:fetch.

repo:fetch([remote[, options]]) hace fetch desde un remoto y devuelve estadísticas de transferencia.

Argumentos:

• remote (cadena, opcional): Nombre remoto. El valor predeterminado es "origin".
• options (tabla, opcional): Opciones de fetch. Campos admitidos:
  • refspecs (string|string[], opcional): Una refspec o una matriz de refspecs.
  • auth (tabla, opcional): Configuración de autenticación remota. Utiliza la misma estructura que ptool.git.clone(...).

Devuelve:

• received_objects (entero)
• indexed_objects (entero)
• local_objects (entero)
• total_objects (entero)
• received_bytes (entero)

Ejemplo:

local stats = repo:fetch("origin", {
  auth = {
    kind = "ssh_agent",
  },
})

print(stats.received_objects, stats.received_bytes)

push

Unreleased - Introducido.

Nombre de la API canónica: ptool.git.Repo:push.

repo:push([remote[, refspecs[, options]]]) hace push de refs a un remoto.

Argumentos:

• remote (cadena, opcional): Nombre remoto. El valor predeterminado es "origin".
• refspecs (string|string[], opcional): Una refspec o una matriz de refspecs.
• options (tabla, opcional): Opciones de push. Campos admitidos:
  • auth (tabla, opcional): Configuración de autenticación remota. Utiliza la misma estructura que ptool.git.clone(...).

Comportamiento:

• Cuando se omite refspecs, ptool intenta hacer push de la rama local actual a la rama del mismo nombre en el remoto.
• Omitir refspecs cuando HEAD está detached genera un error.

Ejemplo:

repo:push("origin", nil, {
  auth = {
    kind = "ssh_agent",
  },
})

repo:push("origin", "refs/heads/main:refs/heads/main")