MMOframework
Pourquoi l'IA Playground Bibliothèques Documentation Rechercher Agence
FR EN
MMOframework · une réalisation Hydra Agency Documentation · MCP
Index

Repository

MMO\git\helpers · 1 symbole · générée le 27 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
Espace de noms
MMO\git\helpers
Étend
aEntry
Implémente
iSerializable
Voir
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://mmoframework.fr/fr/documentation/mmo.git/php/helpers/Repository.md#repository-exec), which runs `git <cmd>` in the repository folder with A repository is [`iSerializable`](https://mmoframework.fr/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()
attribute($diff, $paths)Say which commit of a range made each change of its diff (DiffLine::$commit): on an added line, the commit that wrote it as it reads at the end of the range; on a removed line, the commit that…
blame($cmd, $boundary)Read git blame --line-porcelain: each line's block starts <hash> <line in the commit> <line in the file> and ends with the line itself, after a tab.
checkout($branch, $create)Runs a git checkout call.
checkoutAndPull($branch)Checkout a branch, then pull it when it is behind its upstream.
children($from, $to)
clearEntries()
commit($message, $options)Runs a git commit call.
createBranch($branch)
deleteBranch($branch, $force)
diff($from, $to, $paths, $context, $ignoreWhitespace)What changed between two revisions, file by file, line by line.
diffCommit($commit, $paths, $context, $ignoreWhitespace)What one commit changed: diff from its first parent, or from nothing for the first commit of the history.
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.
log($range, $paths, $max)The commits of a range, the newest first, as git log lists them.
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)

Propriétés10

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

Méthodes69

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
retournestring

addTag($tag, $message)

Repository.php:883

Add an annotated tag at the current position.

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

archive($ref, $folder, $options)

Repository.php:618

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)
retournestring
lèvewhen the destination does not exist

attribute($diff, $paths)

Repository.php:543

Say which commit of a range made each change of its diff (DiffLine::$commit): on an added line, the commit that wrote it as it reads at the end of the range; on a removed line, the commit that removed it.

function attribute(MMO\git\helpers\Diff $diff, ?array $paths = null): MMO\git\helpers\DiffTwo blames per file: `git blame` of the new file, whose lines older than the range stay unattributed, and `git blame --reverse` of the old one, which gives the last commit where a removed line still existed -- the one that removed it is that commit's child in the range (the first one, after a fork). Both follow renames.
$diffDiffmade by diff between two revisions, the first an ancestor of the second
$paths = nullnull | arrayonly these files of it (by their new or old path); null: all of them
retourneDiff$diff, its changed lines attributed
lèvewhen $diff is against the working tree, which has no commit to name
$diff = $repo->attribute($repo->diff('v3.0.1', 'develop'), ['src/helpers/Repository.php']); foreach ($diff->getFile('src/helpers/Repository.php')->hunks[0]->lines as $line) {echo substr($line->commit ?? '', 0, 7), "\t", $line->type, $line->text, "\n";}

blame($cmd, $boundary)

Repository.php:581

Read git blame --line-porcelain: each line's block starts <hash> <line in the commit> <line in the file> and ends with the line itself, after a tab.

protected function blame(string $cmd, bool $boundary): array
$cmdstring
$boundaryboolkeep the lines blamed on the range's first revision (boundary)
retournearraystring> {line in the file: full hash}

checkout($branch, $create)

Repository.php:695

Runs a git checkout call.

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

checkoutAndPull($branch)

Repository.php:710

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
retournestatic

children($from, $to)

Repository.php:599
protected function children(string $from, string $to): array
$fromstring
$tostring
retournearraystring[]> {full hash: its children between $from and $to, the oldest first}; $from's included

commit($message, $options)

Repository.php:450

Runs a git commit call.

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

diff($from, $to, $paths, $context, $ignoreWhitespace)

Repository.php:501

What changed between two revisions, file by file, line by line.

function diff( string $from, ?string $to = null, array $paths = [], int $context = 3, bool $ignoreWhitespace = false ): MMO\git\helpers\DiffRenames are found (`--find-renames`). Files git does not track are not part of a diff against the working tree. Whatever the configuration says (an external diff, `diff.noprefix`, quoted paths...), git is asked for its plain patch, the one [`Diff::Parse`](https://mmoframework.fr/fr/documentation/mmo.git/php/helpers/Diff.md#diff-parse) reads.
$fromstringthe old revision (a hash, a branch, a tag, HEAD~2...)
$to = nullnull | stringthe new revision; null: the working tree
$paths = []arrayonly these paths (files or folders, from the repository's root); none: every path
$context = 3inthow many unchanged lines git keeps around each change
$ignoreWhitespace = falseboolleave out changes in whitespace alone (-w)
retourneDiff
lèvewhen a revision does not exist
foreach ($repo->diff('v3.0.1', 'develop', ['src']) as $file) { echo $file->status, ' ', $file->path(), ' +', $file->additions(), ' -', $file->deletions(), "\n"; }

diffCommit($commit, $paths, $context, $ignoreWhitespace)

Repository.php:520

What one commit changed: diff from its first parent, or from nothing for the first commit of the history.

function diffCommit( string $commit, array $paths = [], int $context = 3, bool $ignoreWhitespace = false ): MMO\git\helpers\Diff
$commitstring
$paths = []arraydiff
$context = 3intdiff
$ignoreWhitespace = falsebooldiff
retourneDifffrom the parent's hash (or the empty tree's) to $commit
$repo->diffCommit('b93d05f')->getFile('src/helpers/Repository.php');

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
retournestring

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
retournestringgit's standard output
lève

execTrim($cmd, $throwOnExitCode, $exitCode)

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

getBranch()

Repository.php:643

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

function getBranch(): string
retournestring

getChangedEntries()

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

getCommitHash($short)

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

getCommitVersion()

Repository.php:791

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

getRemoteName($url, $fetch)

Repository.php:868

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

getRemotes($direction)

Repository.php:837

The configured remotes.

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

getRevisionCount($branch1, $branch2)

Repository.php:805

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

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

getUpstreamOf($branch)

Repository.php:730

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

function getUpstreamOf(?string $branch = null): ?string
$branch = nullnull | stringnull: the current branch
retournenull | 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
retournebool

isClean()

Repository.php:177
function isClean(): bool
retournebooltrue 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
retournearrayaEntry> keyed by the path relative to this repository

listBranches($incLocal, $incRemote)

Repository.php:673

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
retournearraya 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
retournearrayModule> keyed by the path relative to this repository

listTags($pattern)

Repository.php:893

List the repository tags, most recent version first.

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

log($range, $paths, $max)

Repository.php:822

The commits of a range, the newest first, as git log lists them.

function log(string $range = 'HEAD', array $paths = [], ?int $max = null): array
$range = 'HEAD'stringwhat git log takes: A..B (the commits of B that A does not have), a branch, a hash...
$paths = []arrayonly the commits that touch these paths; none: every commit
$max = nullnull | intat most that many commits; null: all of them
retournearray
lèvewhen the range does not resolve
foreach ($repo->log('v3.0.1..develop') as $commit) {echo $commit->short(), ' ', $commit->subject, "\n";}

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
retourneaEntry

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
retournestring

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
retournestring

pushMasterVersion($masterBranch, $where, $defaultVersion)

Repository.php:944

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
retournestatic

resolve($ref)

Repository.php:762

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

function resolve(string $ref = 'HEAD'): string
$ref = 'HEAD'string
retournestring
lèvewhen 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://mmoframework.fr/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
retournearray

show($revision, $filename)

Repository.php:932

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
retournestringthe 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:912

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
retournestringthe new version, without its v prefix

test($cmd)

Repository.php:137
function test(string $cmd): bool
$cmdstring
retournebooltrue 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
retournevoid

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

__construct($filename, $status, $origin)

Repository.php:51
function __construct(string $filename, int $status = 0, ?string $origin = null)
$filenamestring
$status = 0int
$origin = nullnull | string
Membres hérités (44)
ConstantesDéclaré parDescription
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
PropriétésDéclaré parDescription
filenameaEntry
originaEntry
parentaEntry
statusaEntry
STATUS_TEXTaEntry
MéthodesDéclaré parDescription
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.