Index

Repository

MMO\git\helpers · 1 symbol · generated 5 Oct 2026

class

Repository

Repository.php:30

A local git repository, driven by the git command line.

class MMO\git\helpers\Repository extends MMO\git\classes\aEntry implements MMO\core\interfaces\iSerializable
Namespace
MMO\git\helpers
Extends
aEntry
Implements
iSerializable
See
Process and throws an eRuntime on a non-zero exit code, so a failing git command is an exception rather than a string nobody reads. The defaults (bin, sudo, timeout) come from the, Git module and can be overridden per instance.
Every call goes through [`exec`](https://mcp.mmoframework.fr/documentation/mmo.git/php/helpers/Repository.md#repository-exec), which runs `git <cmd>` in the repository folder with A repository is [`iSerializable`](https://mcp.mmoframework.fr/documentation/mmo.core/php/interfaces/iSerializable.md#iserializable), so it can be declared straight in a configuration file: `{"$": "MMO\\git\\helpers\\Repository", "filename": "{root}"}`. That is how `mmo.admin`'s `ProductionController` receives the project's repository.
$repo = new Repository('/var/www/project'); if ($repo->update()->hasChanges()) { foreach ($repo->getChangedEntries() as $entry) {echo $entry->relativeFilename(), ': ', $entry->getStatusText(), "\n";} }

Index

ahead
behind
bin
branch
entries
id
runAsSudo
timeout
upstream
valid
add($file, $option)Runs a git add call.
addTag($tag, $message)Add an annotated tag at the current position.
archive($ref, $folder, $options)Export a ref's tree into a folder: tracked files only, no .git, nothing the working tree happens to carry.
assertValid()
checkout($branch, $create)Runs a git checkout call.
checkoutAndPull($branch)Checkout a branch, then pull it when it is behind its upstream.
clearEntries()
commit($message, $options)Runs a git commit call.
createBranch($branch)
deleteBranch($branch, $force)
Escape($arg) staticEscape one argument for the shell.
exec($cmd, $throwOnExitCode, $exitCode)Run a git command in the repository folder.
execTrim($cmd, $throwOnExitCode, $exitCode)
fetch($opts)
getAhead()
getBehind()
getBranch()The current branch, or -- on a detached HEAD, which has no branch -- the short commit hash.
getChangedEntries()
getCommit($format)
getCommitHash($short)
getCommitVersion()A version for the current commit, derived from the most recent tag.
getEntriesStatus()
getEntriesStatusText($sep)
getEntry($relativeFilename)
getFetchRemotes()
getModuleStatus()
getModuleStatusText($sep)
getPushRemotes()
getRemoteName($url, $fetch)The name of the remote serving $url.
getRemotes($direction)The configured remotes.
getRevisionCount($branch1, $branch2)How many commits $branch2 has that $branch1 does not.
getUpstream()
getUpstreamOf($branch)The remote-tracking branch a local branch follows, e.g.
hasChanges()
hasDiff($filter, $files, $ref)Check whether there are differences against $ref.
init()
isClean()
isDetached()
isValid()
isValidRemote($url)
list()Every tracked entry, recursing into the submodules.
listBranches($incLocal, $incRemote)Runs a git branch call.
listModules()The submodules declared by this repository.
listTags($pattern)List the repository tags, most recent version first.
makeEntry($file, $status, $sub, $origin)Build (or refresh) one entry of update, choosing File or Module from the <sub> field git reported.
merge($branch, $options)Runs a git merge call.
mtime($filename, $options)
pull($remote, $branch, $options)Pull a specific branch from a remote.
push($remote, $branch, $options)Push a specific branch (or all branches) to a remote.
pushMasterVersion($masterBranch, $where, $defaultVersion)Merge the current branch into the master branch and tag the version.
realCommand($cmd)
remove($file, $option)
resolve($ref)Resolve any commit-ish (a branch, a tag, HEAD~2, ...) to its full hash.
restoreTime($filename, $options)
serialize($path, $serializer)Only the folder and the status are persisted: everything else (update's entries, the branch, the ahead/behind counters) is a cache of what git said at one moment, and is re-read on the next @s…
setFolder($folder)
show($revision, $filename)Show the content of a file from another branch/revision.
status()
tagVersion($message, $where, $inc, $default)Tag the current commit with the next version after the most recent v* tag.
test($cmd)
unserialize($data, $path, $instances)
update()Read git status into this repository's flags and entries.
__construct($filename, $status, $origin)

Properties10

ahead

protected int $ahead = 0
Type
int

behind

protected int $behind = 0
Type
int

branch

protected ?string $branch = null
Type
null | string

entries

protected array $entries = []
Type
array

runAsSudo

bool $runAsSudo
Type
bool

upstream

protected ?string $upstream = null
Type
null | string

valid

protected bool $valid = false
Type
bool

Methods63

add($file, $option)

Repository.php:396

Runs a git add call.

function add(string $file, string $option = ''): string
$filestringthe file to add, relative to the repository or absolute
$option = ''string
returnsstring

addTag($tag, $message)

Repository.php:739

Add an annotated tag at the current position.

function addTag(string $tag, ?string $message = null): string
$tagstring
$message = nullnull | stringdefaults to the tag name
returnsstring

archive($ref, $folder, $options)

Repository.php:492

Export a ref's tree into a folder: tracked files only, no .git, nothing the working tree happens to carry. This is what a release must be packaged from -- BuildTask.

function archive(string $ref, string $folder, string $options = ''): string
$refstringthe commit-ish to export
$folderstringan existing destination folder
$options = ''stringpassed to git archive (e.g. --worktree-attributes)
returnsstring
throwswhen the destination does not exist

checkout($branch, $create)

Repository.php:569

Runs a git checkout call.

function checkout(string $branch, bool $create = false): string
$branchstring
$create = falseboolcreate the branch
returnsstring

checkoutAndPull($branch)

Repository.php:584

Checkout a branch, then pull it when it is behind its upstream.

function checkoutAndPull(string $branch): staticThe remote is whatever the branch actually tracks -- not a hard-coded name, so this works the same on a repository whose remote is `origin` and on one whose remote is `github`.
$branchstring
returnsstatic

commit($message, $options)

Repository.php:450

Runs a git commit call.

function commit(string $message, string $options = ''): bool
$messagestringthe commit message
$options = ''string
returnsboolfalse when there was nothing to commit, which is not an error

Escape($arg)

staticRepository.php:102

Escape one argument for the shell. Use it for anything that is not a literal in the source.

static function Escape(?string $arg): string
$argnull | string
returnsstring

exec($cmd, $throwOnExitCode, $exitCode)

Repository.php:118

Run a git command in the repository folder.

function exec(string $cmd, bool $throwOnExitCode = true, ?int &$exitCode = null): string
$cmdstringthe command, without the leading git
$throwOnExitCode = trueboolthrow when git exits non-zero, instead of returning what it printed
$exitCode = nullnull | intreceives the exit code
returnsstringgit's standard output
throws

execTrim($cmd, $throwOnExitCode, $exitCode)

Repository.php:132
function execTrim(string $cmd, bool $throwOnExitCode = true, ?int &$exitCode = null): string
$cmdstring
$throwOnExitCode = truebool
$exitCode = nullnull | int
returnsstringgit's output with surrounding whitespace removed -- what most porcelain-free calls want.

getBranch()

Repository.php:517

The current branch, or -- on a detached HEAD, which has no branch -- the short commit hash.

function getBranch(): string
returnsstring

getChangedEntries()

Repository.php:182
function getChangedEntries(): array
returnsarrayaEntry> the entries reported by the last update, keyed by relative path.

getCommitHash($short)

Repository.php:625
function getCommitHash(bool $short = true): string
$short = truebool
returnsstringthe short hash of the current commit.

getCommitVersion()

Repository.php:665

A version for the current commit, derived from the most recent tag.

function getCommitVersion(): stringA repository with no tag yet is not an error -- it simply has no version to describe, so the commit hash stands in for one.
returnsstring

getRemoteName($url, $fetch)

Repository.php:724

The name of the remote serving $url.

function getRemoteName(string $url, bool $fetch = true): ?string
$urlstring
$fetch = trueboollook at the fetch urls rather than the push ones
returnsnull | string

getRemotes($direction)

Repository.php:693

The configured remotes.

function getRemotes(string $direction = 'fetch'): array
$direction = 'fetch'stringfetch or push
returnsarray{name: url}

getRevisionCount($branch1, $branch2)

Repository.php:679

How many commits $branch2 has that $branch1 does not.

function getRevisionCount(string $branch1, ?string $branch2 = null): int
$branch1string
$branch2 = nullnull | stringnull: the current HEAD
returnsint

getUpstreamOf($branch)

Repository.php:604

The remote-tracking branch a local branch follows, e.g. origin/main.

function getUpstreamOf(?string $branch = null): ?string
$branch = nullnull | stringnull: the current branch
returnsnull | stringnull when the branch tracks nothing

hasDiff($filter, $files, $ref)

Repository.php:471

Check whether there are differences against $ref.

function hasDiff(?string $filter = null, string $files = '', string $ref = 'HEAD'): bool
$filter = nullnull | stringSelect only files that are Added (A), Copied (C), Deleted (D), Modified (M), Renamed (R), have their type (i.e. regular file, symlink, submodule, ...) changed (T), are Unmerged (U), are Unknown (X), or have had their pairing Broken (B). Any combination of the filter characters (including none) can be used
$files = ''stringlist of files to check. If empty, checks for any change
$ref = 'HEAD'stringif @tag, replaced by the most recent tag
returnsbool

isClean()

Repository.php:177
function isClean(): bool
returnsbooltrue when the working tree has nothing uncommitted -- what a release must build from.

list()

Repository.php:200

Every tracked entry, recursing into the submodules.

function list(): array
returnsarrayaEntry> keyed by the path relative to this repository

listBranches($incLocal, $incRemote)

Repository.php:547

Runs a git branch call.

function listBranches(bool $incLocal = true, bool $incRemote = false): array
$incLocal = trueboolinclude the local branches
$incRemote = falseboolinclude the remote-tracking branches
returnsarraya list of branch names, without the * marker and without the symbolic HEAD -> entry

listModules()

Repository.php:224

The submodules declared by this repository.

function listModules(): array
returnsarrayModule> keyed by the path relative to this repository

listTags($pattern)

Repository.php:749

List the repository tags, most recent version first.

function listTags(?string $pattern = null): array
$pattern = nullnull | stringa shell wildcard pattern to match tags against
returnsarray

makeEntry($file, $status, $sub, $origin)

Repository.php:347

Build (or refresh) one entry of update, choosing File or Module from the <sub> field git reported.

protected function makeEntry(string $file, int $status, string $sub, ?string $origin = null): MMO\git\classes\aEntry
$filestringthe path relative to this repository
$statusint
$substringthe four-character <sub> field (N..., or S<c><m><u> for a submodule)
$origin = nullnull | string
returnsaEntry

pull($remote, $branch, $options)

Repository.php:436

Pull a specific branch from a remote.

function pull(string $remote = '', string $branch = '', string $options = ''): stringWith no remote and no branch the command is a plain `git pull`, and therefore behaves as the repository's own configuration says.
$remote = ''string
$branch = ''string
$options = ''string
returnsstring

push($remote, $branch, $options)

Repository.php:417

Push a specific branch (or all branches) to a remote.

function push(string $remote = '', string $branch = '', string $options = ''): stringWith no remote and no branch the command is a plain `git push`, and therefore behaves as the repository's `push.default` setting says.
$remote = ''string
$branch = ''string
$options = ''string
returnsstring

pushMasterVersion($masterBranch, $where, $defaultVersion)

Repository.php:800

Merge the current branch into the master branch and tag the version.

function pushMasterVersion( string $masterBranch = 'master', int $where = MMO\core\versions\PATCH, string $defaultVersion = '1.0.0' ): static
$masterBranch = 'master'string
$where = MMO\core\versions\PATCHintwhich part of the version to increase (inc)
$defaultVersion = '1.0.0'string
returnsstatic

resolve($ref)

Repository.php:636

Resolve any commit-ish (a branch, a tag, HEAD~2, ...) to its full hash.

function resolve(string $ref = 'HEAD'): string
$ref = 'HEAD'string
returnsstring
throwswhen the ref does not resolve

serialize($path, $serializer)

Repository.php:72

Only the folder and the status are persisted: everything else (update's entries, the branch, the ahead/behind counters) is a cache of what git said at one moment, and is re-read on the next update.

function serialize(string $path, callable $serializer): arrayThe `$` key is what tells [`unserialize`](https://mcp.mmoframework.fr/documentation/mmo.core/php/objects.md#unserialize) which class to rebuild -- without it a serialized repository comes back as a plain array.
$pathstring
$serializercallable
returnsarray

show($revision, $filename)

Repository.php:788

Show the content of a file from another branch/revision.

function show(string $revision, string $filename): string
$revisionstringbranch or revision/ref
$filenamestringrelative to the repository root
returnsstringthe content of the file
$repo->show('develop', 'myfile.php'); //the content of 'myfile.php' on the branch develop

tagVersion($message, $where, $inc, $default)

Repository.php:768

Tag the current commit with the next version after the most recent v* tag.

function tagVersion( ?string $message = null, int $where = MMO\core\versions\PATCH, int $inc = 1, string $default = '1.0.0' ): string
$message = nullnull | stringwhen given, the tag is pushed as well
$where = MMO\core\versions\PATCHintwhich part of the version to increase (inc)
$inc = 1int
$default = '1.0.0'stringthe version to start from when the repository has no v* tag yet
returnsstringthe new version, without its v prefix

test($cmd)

Repository.php:137
function test(string $cmd): bool
$cmdstring
returnsbooltrue when the command succeeded, without throwing and without caring what it printed.

unserialize($data, $path, $instances)

Repository.php:78
function unserialize( array $data, string $path, Psr\Container\ContainerInterface|array &$instances ): void
$dataarray
$pathstring
$instancesContainerInterface | array
returnsvoid

update()

Repository.php:246

Read git status into this repository's flags and entries.

function update(): staticUses `--porcelain=2 -z`: a stable machine format whose fields never need quoting, so a filename holding a space, a quote or a newline survives the round trip -- which the human-readable `git status` cannot promise.
returnsstatic

__construct($filename, $status, $origin)

Repository.php:51
function __construct(string $filename, int $status = 0, ?string $origin = null)
$filenamestring
$status = 0int
$origin = nullnull | string
Inherited members (44)
ConstantsDeclared byDescription
CAN_BE_ADDEDiEntry
CAN_BE_COMMITEDiEntry
COMMIT_CHANGEDiEntry
ENTRY_STATUSiEntry
INDEX_ADDEDiEntry
INDEX_COPIEDiEntry
INDEX_DELETEDiEntry
INDEX_IGNOREDiEntry
INDEX_MODIFIEDiEntry
INDEX_RENAMEDiEntry
INDEX_UNMERGEDiEntry
INDEX_UNTRACKEDiEntry
MODULE_STATUSiEntry
TRACKED_CHANGESiEntry
UNKNOWN_ERRORiEntry
UNTRACKED_CHANGESiEntry
WORKTREE_ADDEDiEntry
WORKTREE_COPIEDiEntry
WORKTREE_DELETEDiEntry
WORKTREE_IGNOREDiEntry
WORKTREE_MODIFIEDiEntry
WORKTREE_RENAMEDiEntry
WORKTREE_UNMERGEDiEntry
WORKTREE_UNTRACKEDiEntry
PropertiesDeclared byDescription
filenameaEntry
originaEntry
parentaEntry
statusaEntry
STATUS_TEXTaEntry
MethodsDeclared byDescription
addStatus($flags)aEntry
clearStatus($flags)aEntry
debugName()aEntry
getFilename()aEntry
getOrigin()aEntry
getParent()aEntry
getStatus()aEntry
getStatusText($sep)aEntry
relativeFilename()aEntryThe filename relative to the repository this entry belongs to.
setOrigin($origin)aEntry
setParent($parent)aEntry
setStatus($flags, $origin)aEntryReplace the status flags, and -- because git reports a rename's previous path alongside its status -- optionally the origin in the same call.
StatusFlags($flags)aEntryRead the two-character <XY> field of a git status --porcelain=2 entry.
StatusModuleFlags($flags)aEntryRead the four-character <sub> field of a git status --porcelain=2 entry (N... for a plain file, S<c><m><u> for a submodule).
StatusText($status, $sep)aEntryConvert git status constants to text.