toolkit

Git

Runs git commands against a repository: status, add, commit, log, diff and restore.

Git:: Phlat\Toolkit\Git 39 methods

Repository 3

  • isRepo Whether $path is inside a repository: a .git folder (or file, for worktrees and submodules) in it or a parent.
  • init Creates a repository with $defaultBranch.
  • root The top folder of the repository holding $path, or null outside one.

Status 2

  • isDirty Returns true if there are any staged or unstaged changes.
  • status Returns [['status' => 'M', 'path' => '...'], ...] for changed files.

Staging & commits 5

  • add Stages files, or everything when none are given.
  • remove Force-removes tracked paths from the index and working tree (also drops their .gitmodules entry).
  • commit Returns the full result, not just ok - a commit fails for reasons (identity, hooks, a lock) worth logging.
  • commitAll Stages and commits in one step.
  • reset Points the index entries for $files back at HEAD, leaving the working tree alone.

Objects 14

  • resolve The object $rev names ("HEAD", "HEAD^{tree}"), or null if it names nothing - as HEAD does before the first commit.
  • prefix Where $path sits inside its repository ("data/"), which turns a path relative to it into a tree path.
  • tree A tree's entries keyed by name, each ['mode', 'type', 'hash']. $tree is any tree-ish ("HEAD:blog/post"); [] if it doesn't exist.
  • makeTree Writes a tree from entries shaped like tree()'s and returns its hash.
  • hashFiles Stores files as blobs and returns their hashes keyed by file.
  • ignored Those of $files that .gitignore excludes, tracked or not.
  • commitTree Writes a commit of $tree on $parent (null for the first) and returns its hash in the output. $author is "Name <email>".
  • advance Moves HEAD's branch to $commit, only if it is still at $from (null: has no commit yet) - a check against a writer that got there first.
  • log Returns [['hash' => '...', 'author' => '...', 'date' => '...', 'message' => '...'], ...].
  • diff The diff of the working tree, or of what is staged, optionally for one file.
  • changed The files that differ between two commits, relative to $path, limited to $pathspec; null if git can't compare them.
  • show Returns the patch for a single commit, without the commit message header.
  • restore Restores a path's contents from $ref into the working tree, leaving the change uncommitted.
  • readFile Returns a file's raw content as it existed at $ref, or null if it didn't exist there.

Branches 5

Tags 1

  • latestTag Most recent tag reachable from HEAD, or null if there are none.

Submodules 2

  • submoduleAdd Adds a repository as a submodule.
  • submoduleDeinit Unregisters a submodule and removes its working directory, leaving the gitlink staged for removal.

Remote 7

  • push Returns the full result, not just ok - push commonly fails for reasons (auth, non-fast-forward) worth showing the caller. $upstream makes $remote/$branch the branch's upstream, so a first push to an empty remote also sets up tracking.
  • pull Returns the full result, not just ok - pull commonly fails for reasons (auth, conflicts) worth showing the caller. $ffOnly refuses anything but a fast-forward, so it can never merge or leave conflicts in the working tree.
  • fetch Returns the full result, not just ok - fetch commonly fails for reasons (auth, unreachable host) worth showing the caller.
  • lastFetched When the remote was last fetched (unix time, from git's own FETCH_HEAD), or null if it never has been.
  • fetchTags Fetches tags from a remote.
  • remoteUrl The URL of a remote, or null when none is set.
  • aheadBehind Commits the current branch is ahead/behind its remote tracking branch, or null if there's no fetched upstream.

Repository

isRepo

Git::isRepo(string $path): bool

Whether $path is inside a repository: a .git folder (or file, for worktrees and submodules) in it or a parent.

Reads the filesystem instead of running git, since the admin asks on every request.

Parameters (1)
$path string

Returns bool

phlat/src/Toolkit/Git.php:17

init

Git::init(string $path, string $defaultBranch = 'main'): bool

Creates a repository with $defaultBranch.

Parameters (2)
$path string
$defaultBranch string = 'main'

Returns bool

phlat/src/Toolkit/Git.php:29

root

Git::root(string $path): ?string

The top folder of the repository holding $path, or null outside one.

Parameters (1)
$path string

Returns ?string

phlat/src/Toolkit/Git.php:35

Status

isDirty

Git::isDirty(string $path): bool

Returns true if there are any staged or unstaged changes.

Parameters (1)
$path string

Returns bool

phlat/src/Toolkit/Git.php:44

status

Git::status(string $path, ?string $file = null): array

Returns [['status' => 'M', 'path' => '...'], ...] for changed files.

Parameters (2)
$path string
$file ?string = null

Returns array

phlat/src/Toolkit/Git.php:50

Staging & commits

add

Git::add(string $path, string ...$files): bool

Stages files, or everything when none are given.

Parameters (2)
$path string
...$files string

Returns bool

phlat/src/Toolkit/Git.php:70

remove

Git::remove(string $path, string ...$files): bool

Force-removes tracked paths from the index and working tree (also drops their .gitmodules entry).

Parameters (2)
$path string
...$files string

Returns bool

phlat/src/Toolkit/Git.php:77

commit

Git::commit(string $path, string $message, ?string $author = null): ProcResult

Returns the full result, not just ok - a commit fails for reasons (identity, hooks, a lock) worth logging.

Parameters (3)
$path string
$message string
$author ?string = null

Returns ProcResult

phlat/src/Toolkit/Git.php:83

commitAll

Git::commitAll(string $path, string $message, ?string $author = null): ProcResult

Stages and commits in one step.

Pass no $files to stage everything.

Parameters (3)
$path string
$message string
$author ?string = null

Returns ProcResult

phlat/src/Toolkit/Git.php:93

reset

Git::reset(string $path, string ...$files): bool

Points the index entries for $files back at HEAD, leaving the working tree alone.

The paths go in on stdin, as a long list would not fit the command line.

Parameters (2)
$path string
...$files string

Returns bool

phlat/src/Toolkit/Git.php:100

Objects

resolve

Git::resolve(string $path, string $rev = 'HEAD'): ?string

The object $rev names ("HEAD", "HEAD^{tree}"), or null if it names nothing - as HEAD does before the first commit.

Parameters (2)
$path string
$rev string = 'HEAD'

Returns ?string

phlat/src/Toolkit/Git.php:109

prefix

Git::prefix(string $path): string

Where $path sits inside its repository ("data/"), which turns a path relative to it into a tree path.

Parameters (1)
$path string

Returns string

phlat/src/Toolkit/Git.php:116

tree

Git::tree(string $path, string $tree): array

A tree's entries keyed by name, each ['mode', 'type', 'hash']. $tree is any tree-ish ("HEAD:blog/post"); [] if it doesn't exist.

Parameters (2)
$path string
$tree string

Returns array

phlat/src/Toolkit/Git.php:122

makeTree

Git::makeTree(string $path, array $entries): ?string

Writes a tree from entries shaped like tree()'s and returns its hash.

Parameters (2)
$path string
$entries array

Returns ?string

phlat/src/Toolkit/Git.php:139

hashFiles

Git::hashFiles(string $path, array $files): array

Stores files as blobs and returns their hashes keyed by file.

Parameters (2)
$path string
$files array

Returns array

phlat/src/Toolkit/Git.php:150

ignored

Git::ignored(string $path, array $files): array

Those of $files that .gitignore excludes, tracked or not.

Parameters (2)
$path string
$files array

Returns array

phlat/src/Toolkit/Git.php:163

commitTree

Git::commitTree(string $path, string $tree, ?string $parent, string $message, ?string $author = null): ProcResult

Writes a commit of $tree on $parent (null for the first) and returns its hash in the output. $author is "Name <email>".

Parameters (5)
$path string
$tree string
$parent ?string
$message string
$author ?string = null

Returns ProcResult

phlat/src/Toolkit/Git.php:175

advance

Git::advance(string $path, string $commit, ?string $from, string $message): ProcResult

Moves HEAD's branch to $commit, only if it is still at $from (null: has no commit yet) - a check against a writer that got there first.

Parameters (4)
$path string
$commit string
$from ?string
$message string

Returns ProcResult

phlat/src/Toolkit/Git.php:185

log

Git::log(string $path, int $limit = 20, ?string $file = null): array

Returns [['hash' => '...', 'author' => '...', 'date' => '...', 'message' => '...'], ...].

Parameters (3)
$path string
$limit int = 20
$file ?string = null

Returns array

phlat/src/Toolkit/Git.php:191

diff

Git::diff(string $path, ?string $file = null, bool $staged = false): string

The diff of the working tree, or of what is staged, optionally for one file.

Parameters (3)
$path string
$file ?string = null
$staged bool = false

Returns string

phlat/src/Toolkit/Git.php:210

changed

Git::changed(string $path, string $from, string $to, string $pathspec = '.'): ?array

The files that differ between two commits, relative to $path, limited to $pathspec; null if git can't compare them.

Parameters (4)
$path string
$from string
$to string
$pathspec string = '.'

Returns ?array

phlat/src/Toolkit/Git.php:222

show

Git::show(string $path, string $hash, ?string $file = null): string

Returns the patch for a single commit, without the commit message header.

Parameters (3)
$path string
$hash string
$file ?string = null

Returns string

phlat/src/Toolkit/Git.php:232

restore

Git::restore(string $path, string $ref, string $file): bool

Restores a path's contents from $ref into the working tree, leaving the change uncommitted.

Parameters (3)
$path string
$ref string
$file string

Returns bool

phlat/src/Toolkit/Git.php:242

readFile

Git::readFile(string $path, string $ref, string $file): ?string

Returns a file's raw content as it existed at $ref, or null if it didn't exist there.

Parameters (3)
$path string
$ref string
$file string

Returns ?string

phlat/src/Toolkit/Git.php:248

Branches

currentBranch

Git::currentBranch(string $path): string

The name of the checked-out branch.

Parameters (1)
$path string

Returns string

phlat/src/Toolkit/Git.php:258

branches

Git::branches(string $path): array

Returns local branch names.

Parameters (1)
$path string

Returns array

phlat/src/Toolkit/Git.php:264

createBranch

Git::createBranch(string $path, string $name): bool

Creates a branch at the current commit.

Parameters (2)
$path string
$name string

Returns bool

phlat/src/Toolkit/Git.php:271

checkout

Git::checkout(string $path, string $branch): bool

Switches to a branch.

Parameters (2)
$path string
$branch string

Returns bool

phlat/src/Toolkit/Git.php:277

deleteBranch

Git::deleteBranch(string $path, string $name, bool $force = false): bool

Deletes a branch; $force deletes it unmerged.

Parameters (3)
$path string
$name string
$force bool = false

Returns bool

phlat/src/Toolkit/Git.php:283

Tags

latestTag

Git::latestTag(string $path): ?string

Most recent tag reachable from HEAD, or null if there are none.

Parameters (1)
$path string

Returns ?string

phlat/src/Toolkit/Git.php:291

Submodules

submoduleAdd

Git::submoduleAdd(string $path, string $url, string $submodulePath): bool

Adds a repository as a submodule.

Parameters (3)
$path string
$url string
$submodulePath string

Returns bool

phlat/src/Toolkit/Git.php:300

submoduleDeinit

Git::submoduleDeinit(string $path, string $submodulePath): bool

Unregisters a submodule and removes its working directory, leaving the gitlink staged for removal.

Parameters (2)
$path string
$submodulePath string

Returns bool

phlat/src/Toolkit/Git.php:306

Remote

push

Git::push(string $path, string $remote = 'origin', ?string $branch = null, bool $upstream = false, ?int $timeout = null): ProcResult

Returns the full result, not just ok - push commonly fails for reasons (auth, non-fast-forward) worth showing the caller. $upstream makes $remote/$branch the branch's upstream, so a first push to an empty remote also sets up tracking.

Parameters (5)
$path string
$remote string = 'origin'
$branch ?string = null
$upstream bool = false
$timeout ?int = null

Returns ProcResult

phlat/src/Toolkit/Git.php:317

pull

Git::pull(string $path, string $remote = 'origin', ?string $branch = null, bool $ffOnly = false, ?int $timeout = null): ProcResult

Returns the full result, not just ok - pull commonly fails for reasons (auth, conflicts) worth showing the caller. $ffOnly refuses anything but a fast-forward, so it can never merge or leave conflicts in the working tree.

Parameters (5)
$path string
$remote string = 'origin'
$branch ?string = null
$ffOnly bool = false
$timeout ?int = null

Returns ProcResult

phlat/src/Toolkit/Git.php:327

fetch

Git::fetch(string $path, string $remote = 'origin', ?int $timeout = null): ProcResult

Returns the full result, not just ok - fetch commonly fails for reasons (auth, unreachable host) worth showing the caller.

Parameters (3)
$path string
$remote string = 'origin'
$timeout ?int = null

Returns ProcResult

phlat/src/Toolkit/Git.php:337

lastFetched

Git::lastFetched(string $path): ?int

When the remote was last fetched (unix time, from git's own FETCH_HEAD), or null if it never has been.

Parameters (1)
$path string

Returns ?int

phlat/src/Toolkit/Git.php:343

fetchTags

Git::fetchTags(string $path, string $remote = 'origin'): bool

Fetches tags from a remote.

Parameters (2)
$path string
$remote string = 'origin'

Returns bool

phlat/src/Toolkit/Git.php:356

remoteUrl

Git::remoteUrl(string $path, string $remote = 'origin'): ?string

The URL of a remote, or null when none is set.

Parameters (2)
$path string
$remote string = 'origin'

Returns ?string

phlat/src/Toolkit/Git.php:362

aheadBehind

Git::aheadBehind(string $path, string $remote = 'origin', ?string $branch = null): ?array

Commits the current branch is ahead/behind its remote tracking branch, or null if there's no fetched upstream.

Parameters (3)
$path string
$remote string = 'origin'
$branch ?string = null

Returns ?array

phlat/src/Toolkit/Git.php:369