Gitonomy Gitlib

https://github.com/gitonomy/gitlib
Admin
This library provides methods to access Git repository from PHP 8.0+, making shell calls for...
Tokens:48,257
Snippets:401
Trust Score:6.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install gitlib with Composer require

Source: https://github.com/gitonomy/gitlib/blob/main/README.md

Install gitlib via Composer by running this command in your terminal. This is the quickest way to add the library to your project.

```bash
$ composer require gitonomy/gitlib

```

--------------------------------

### Get a Log object from a repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Creates a Log object for the entire repository. This is the simplest way to obtain a log and is the starting point for all log operations.

```php
$log = $repository->getLog();
```

--------------------------------

### Basic gitlib usage with Repository

Source: https://github.com/gitonomy/gitlib/blob/main/README.md

Example usage of gitlib: create a Repository instance, list all branches, and run a fetch. This snippet showcases the primary API for interacting with a Git repository.

```php
<?php

use Gitonomy\Git\Repository;

$repository = new Repository('/path/to/repository');

foreach ($repository->getReferences()->getBranches() as $branch) {
    echo '- '.$branch->getName().PHP_EOL;
}

$repository->run('fetch', ['--all']);

```

--------------------------------

### Get a branch from a repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/branch.md

Creates a Repository object and retrieves the 'master' branch using getReferences()->getBranch().

```php
$repository = new Gitonomy\Git\Repository('/path/to/repository');
$branch = $repository->getReferences()->getBranch('master');
```

--------------------------------

### Logger output for fetch command

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Example output from the logger when running a fetch command. Shows the command, duration, return code, and output.

```text
info run command: fetch "--all"
debug last command (fetch) duration: 23.24ms
debug last command (fetch) return code: 0
debug last command (fetch) output: Fetching origin
```

--------------------------------

### Get a Log object from a revision with offset and limit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/revision.md

Accesses a Log object from a revision using the getLog method, which takes offset and limit parameters. The example returns the last 100 commits.

```php
// Returns 100 lasts commits
$log = $revision->getLog(null, 100);
```

--------------------------------

### Get ReferenceBag from Repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

Retrieve the ReferenceBag object from a Repository using the getReferences method. This is the starting point for accessing tags and branches.

```php
$references = $repository->getReferences();
```

--------------------------------

### Get working copy from Repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Access the working copy of a repository by calling getWorkingCopy() on a Repository object.

```php
$repo = new Repository('/path/to/working-dir');
$wc = $repo->getWorkingCopy();
```

--------------------------------

### Get blob content

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blob.md

Outputs the raw content of the blob. The content is returned as a string.

```php
echo $blob->getContent();
```

--------------------------------

### FileChange range methods

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Methods to get line number ranges for a change.

```APIDOC
## FileChange range methods

### Description
Methods to get line number ranges for a change.

### Methods
- `getOldRangeStart()` - Returns the starting line number in the old file.
- `getOldRangeEnd()` - Returns the ending line number in the old file.
- `getNewRangeStart()` - Returns the starting line number in the new file.
- `getNewRangeEnd()` - Returns the ending line number in the new file.

### Example
```php
echo sprintf('Previously from line %s to %s%s', $change->getOldRangeStart(), $change->getOldRangeEnd(), PHP_EOL);
echo sprintf('Now from line %s to %s%s', $change->getNewRangeStart(), $change->getNewRangeEnd(), PHP_EOL);
```
```

--------------------------------

### Get a commit from a repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Creates a Repository object and retrieves a Commit by its hash. The hash is a string identifier for the commit.

```php
$repository = new Gitonomy\Git\Repository('/path/to/repository');
$commit = $repository->getCommit('a7c8d2b4');
```

--------------------------------

### Get all branches and tags

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

Retrieve all branches, local branches, remote branches, tags, or all references using the respective methods on ReferenceBag.

```php
$branches       = $references->getBranches();
$localBranches  = $references->getLocalBranches();
$remoteBranches = $references->getRemoteBranches();
$tags           = $references->getTags();
$all            = $references->getAll();
```

--------------------------------

### Pass arguments to getLog for branch, path, offset, and limit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Shows the four arguments accepted by getLog: branch, path (string or array), offset, and limit. The first call gets the global log, the second restricts to the master branch, the third limits to the last 10 commits on README, and the fourth does the same for README or UPGRADE files.

```php
// Global log for repository
$log = $repository->getLog();

// Log for master branch
$log = $repository->getLog('master');

// Returns last 10 commits on README file
$log = $repository->getLog('master', 'README', 0, 10);

// Returns last 10 commits on README or UPGRADE files
$log = $repository->getLog('master', ['README', 'UPGRADE'], 0, 10);
```

--------------------------------

### Line object properties

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blame.md

Shows how to access the commit and content of a Line object, and how to get the author name from the commit.

```php
$line->getCommit();  // returns a Commit
$line->getContent(); // returns text

// you can access author from commmit:
$author = $line->getCommit()->getAuthorName();
```

--------------------------------

### Get pending diff with getDiffPending()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Get pending modifications on tracked files using getDiffPending().

```php
$diff = $wc->getDiffPending();
```

--------------------------------

### get

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Reads the content of a specified hook. Throws InvalidArgumentException if the hook does not exist.

```APIDOC
## get

### Description
Reads the content of a specified hook. Throws InvalidArgumentException if the hook does not exist.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The name of the hook (e.g., 'pre-receive').

### Request Example
```php
$content = $hooks->get('pre-receive');
```

### Response
#### Success Response
- **content** (string) - The content of the hook file.

#### Response Example
```php
$content = $hooks->get('pre-receive'); // returns a string
```

### Errors
- **InvalidArgumentException** - Thrown if the hook does not exist.
```

--------------------------------

### Set and get offset and limit on a Log object

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Sets and reads the offset and limit for the log. Use setOffset and setLimit to paginate, and getOffset and getLimit to retrieve the current values.

```php
$log->setOffset(32);
$log->setLimit(40);

// or read it:
$log->getOffset();
$log->getLimit();
```

--------------------------------

### Read Hook Content with get()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Reads the content of a hook. Throws an InvalidArgumentException if the hook does not exist.

```php
$content = $hooks->get('pre-receive'); // returns a string
```

--------------------------------

### Get full commit message

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Returns the full commit message, which can be multiline.

```php
$commit->getMessage();
```

--------------------------------

### Get Hooks Object from Repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Retrieves the Hooks object from a Repository instance, which is the entry point for managing git hooks.

```php
$hooks = $repository->getHooks();
```

--------------------------------

### Get staged diff with getDiffStaged()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Get a Diff object of modifications pending in the staging area using getDiffStaged().

```php
$diff = $wc->getDiffStaged();
```

--------------------------------

### Set environment variables for git commands

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Sends environment variables to git commands using the 'environment_variables' option. The example sets an array with a single variable 'GIT_'.

```php
$repository = new Gitonomy\Git\Repository('/tmp/foo', ['environment_variables' => ['GIT_']])
```

--------------------------------

### getLines

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blame.md

Returns an array of lines indexed starting from 1. Each line object provides access to the commit and content.

```APIDOC
## getLines

### Description
Returns an array of lines indexed starting from 1. Each line object provides access to the commit and content.

### Method
PHP method

### Endpoint
$blame->getLines()

### Parameters
None

### Request Example
```php
foreach ($blame->getLines() as $lineNumber => $line) {
    $commit = $line->getCommit();
    echo $lineNumber.': '.$line->getContent().'    - '.$commit->getAuthorName().PHP_EOL;
}
```

### Response
#### Success Response
Returns an array of Line objects indexed from 1.

#### Response Example
```php
array(
    1 => Line,
    2 => Line,
    ...
)
```
```

--------------------------------

### Get subject and body of commit message

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Retrieves the subject line and the body of the commit message separately.

```php
// The first line
$commit->getSubjectMessage();

// The body (rest of the message)
$commit->getBodyMessage();
```

--------------------------------

### Check existence of branches and tags

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

Use hasBranch and hasTag methods to test if a branch or tag exists. The example checks for 'master' branch and '0.1' tag.

```php
if ($references->hasBranch('master') && $references->hasTag('0.1')) {
    echo 'Good start!'.PHP_EOL;
}
```

--------------------------------

### Get a Blob by hash

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blob.md

Retrieves a Blob object from a repository using its hash identifier. The repository path must be valid and the hash must exist in the repository.

```php
$repository = new Gitonomy\Git\Repository('/path/to/repository');
$blob = $repository->getBlob('a7c8d2b4');
```

--------------------------------

### Get last modification of a file

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Retrieves the last modification of a file (e.g., 'README') and prints its author, date, and message.

```php
$last = $commit->getLastModification('README');

echo 'Last README modification'.PHP_EOL;
echo '  Author: '.$last->getAuthorName().PHP_EOL;
echo '    Date: '.$last->getAuthorDate()->format('d/m/Y').PHP_EOL;
echo ' Message: '.$last->getMessage();
```

--------------------------------

### Get line number ranges

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Prints the line number ranges for a FileChange object using the getOldRangeStart, getOldRangeEnd, getNewRangeStart, and getNewRangeEnd methods.

```php
echo sprintf('Previously from line %s to %s%s', $change->getOldRangeStart(), $change->getOldRangeEnd(), PHP_EOL);
echo sprintf('Now from line %s to %s%s', $change->getNewRangeStart(), $change->getNewRangeEnd(), PHP_EOL);
```

--------------------------------

### Get specific branch or tag

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

Retrieve a specific branch or tag using getBranch, getLocalBranch, getRemoteBranch, or getTag. Throws ReferenceNotFoundException if the reference cannot be resolved.

```php
$master  = $references->getBranch('master');
$feat123 = $references->getLocalBranch('feat123');
$feat456 = $references->getRemoteBranch('origin/feat456');
$v0_1    = $references->getTag('0.1');
```

--------------------------------

### Get blob mimetype

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blob.md

Returns the mimetype of the blob using the finfo extension. Requires the finfo extension to be enabled.

```php
echo $blob->getMimetype();
```

--------------------------------

### Get root tree from commit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/tree.md

Retrieves the root tree associated with a commit using the getTree method on the commit object. This tree serves as the entry point for accessing all files in the repository.

```php
$tree = $commit->getTree();
```

--------------------------------

### Get diff from Log

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Computes a diff from a Log object obtained via the Repository's getLog method. The Log object provides a getDiff method.

```php
$log  = $repository->getLog('master@{2 days ago}..master');
$diff = $log->getDiff();
```

--------------------------------

### Iterate over blame lines

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blame.md

Iterates over each line of a blame, printing the line number, content, and author name. The getLines method returns an array indexed starting from 1.

```php
$blame = $repository->getBlame('master', 'README.md');

foreach ($blame->getLines() as $lineNumber => $line) {
    $commit = $line->getCommit();
    echo $lineNumber.': '.$line->getContent().'    - '.$commit->getAuthorName().PHP_EOL;
}
```

--------------------------------

### Get diff from Repository

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Computes a diff for a revision range using the Repository object's getDiff method. The revision can be a commit or a range.

```php
$diff = $repository->getDiff('master@{2 days ago}..master');
```

--------------------------------

### Get author and committer details

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Retrieves author and committer information from a commit. The author is the creator of the modification, while the committer is responsible for introducing it to the repository. Date methods return DateTime objects.

```php
// Author
$commit->getAuthorName();
$commit->getAuthorEmail();
$commit->getAuthorDate(); // returns a DateTime object

// Committer
$commit->getCommitterName();
$commit->getCommitterEmail();
$commit->getCommitterDate(); // returns a DateTime object
```

--------------------------------

### Resolve a path in a tree

Source: https://github.com/gitonomy/gitlib/blob/main/doc/tree.md

Uses the resolvePath method to directly access a sub-file or subdirectory by its path. The example checks that the resolved path is a Tree instance.

```php
$source = $tree->resolvePath('src/Gitonomy/Git');

$source instanceof Tree;
```

--------------------------------

### Access commit information from a reference

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

On a Branch or Tag object, get the associated commit, commit hash, and last modification using getCommit, getCommitHash, and getLastModification.

```php
// Get the associated commit
$commit = $master->getCommit();

// Get the commit hash
$hash = $master->getCommitHash();

// Get the last modification
$lastModification = $master->getLastModification();
```

--------------------------------

### Find branches containing a commit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Finds branches that contain the commit. The first example shows the method signature with placeholder parameters, the second retrieves only local branches, and the third retrieves only remote branches.

```php
$branches       = $commit->getIncludingBranches($includeLocalBranches, $includeRemoteBranches);
$localBranches  = $commit->getIncludingBranches(true, false);
$remoteBranches = $commit->getIncludingBranches(false, true);
```

--------------------------------

### Get short commit message

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Returns a shortened version of the commit message, keeping only the first line or the first 50 characters if the first line is too long.

```php
$commit->getShortMessage();
```

--------------------------------

### Get a revision from a Repository object

Source: https://github.com/gitonomy/gitlib/blob/main/doc/revision.md

Retrieves a revision from a Repository object using the getRevision method with a revision string like 'master@{2 days ago}'.

```php
$revision = $repository->getRevision('master@{2 days ago}');
```

--------------------------------

### Initialize a repository with Admin::init

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Initializes a new repository. Default behavior is to create a bare repository; pass false as the second argument to create a non-bare repository with a working copy.

```php
// Initialize a bare repository
$repository = Gitonomy\Git\Admin::init('/path/to/repository');

// Initialize a non-bare repository
$repository = Gitonomy\Git\Admin::init('/path/to/repository', false);
```

--------------------------------

### Get diff of a commit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Returns the Diff object for a commit. The diff strategy depends on the number of parents: no parent gives the tree content, one parent gives the diff between the commit and its parent, and multiple parents give the diff between the commit and the first common ancestor of all parents.

```php
$diff = $commit->getDiff();
```

--------------------------------

### Admin::init

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Initializes a new Git repository. By default, creates a bare repository; pass false as the second argument to create a non-bare repository with a working copy.

```APIDOC
## Admin::init

### Description
Initializes a new Git repository. By default, creates a bare repository; pass false as the second argument to create a non-bare repository with a working copy.

### Method
Admin::init

### Parameters
- **path** (string) - Required - The filesystem path where the repository will be created.
- **bare** (bool) - Optional - Whether to create a bare repository. Defaults to true.

### Request Example
```php
// Initialize a bare repository
$repository = Gitonomy\Git\Admin::init('/path/to/repository');

// Initialize a non-bare repository
$repository = Gitonomy\Git\Admin::init('/path/to/repository', false);
```

### Response
Returns a Repository instance representing the newly created repository.
```

--------------------------------

### Create a Repository with a path

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Creates a Repository object by passing a path to the constructor. This is the basic way to instantiate a repository.

```php
$repository = new Repository('/path/to/repo');
```

--------------------------------

### Create a Repository with options

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Creates a Repository with options to tune behavior. The debug option enables exceptions on edge cases, and the logger option accepts a Psr\Log\LoggerInterface.

```php
$repository = new Repository('/path/to/repo', [
    'debug'  => true,
    'logger' => new Monolog\Logger(),
]);
```

--------------------------------

### set

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Creates a new hook file with the given content and makes it executable. Throws LogicException if the hook already exists.

```APIDOC
## set

### Description
Creates a new hook file with the given content and makes it executable. Throws LogicException if the hook already exists.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The name of the hook (e.g., 'pre-receive').
- **content** (string) - Required - The content to write to the hook file.

### Request Example
```php
$content = <<<HOOK
#!/bin/bash
echo "Push is disabled"
exit 1

HOOK;

$hooks->set('pre-receive', $content);
```

### Response
#### Success Response
No return value.

### Errors
- **LogicException** - Thrown if the hook already exists.
```

--------------------------------

### Mirror a repository with Admin::mirrorTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Fully mirrors a repository and all references. Takes two arguments: the target path and the source URL. Default is bare; pass false as the third argument for a non-bare mirror.

```php
// Mirror to a bare repository
$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git');

// Mirror to a non-bare repository
$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git', false);
```

--------------------------------

### getDiffPending

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Get a Diff object representing pending modifications on tracked files.

```APIDOC
## getDiffPending

### Description
Get a Diff object representing pending modifications on tracked files.

### Method
getDiffPending

### Returns
- **Diff** - The diff of pending modifications.

### Example
php
$diff = $wc->getDiffPending();

```

--------------------------------

### Set Hook Content with set()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Creates a new hook file with the given content and makes it executable. Throws a LogicException if the hook already exists.

```php
$content = <<<HOOK
#!/bin/bash
echo "Push is disabled"
exit 1

HOOK;

// this hook will reject every push

$hooks->set('pre-receive', $content);
```

--------------------------------

### getDiffStaged

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Get a Diff object representing modifications pending in the staging area.

```APIDOC
## getDiffStaged

### Description
Get a Diff object representing modifications pending in the staging area.

### Method
getDiffStaged

### Returns
- **Diff** - The diff of staged modifications.

### Example
php
$diff = $wc->getDiffStaged();

```

--------------------------------

### Set logger and run command

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Sets a logger on the repository to report every executed command, then runs a fetch command. The logger must be a Psr\Log\LoggerInterface.

```php
$repository->setLogger(new Monolog\Logger('repository'));

$repository->run('fetch', ['--all']);
```

--------------------------------

### Clone a repository and checkout a branch with Admin::cloneBranchTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Clones a repository and points it to a specific branch. In a non-bare repository, the branch will be checked out. Default is bare; pass false as the fourth argument for a non-bare clone.

```php
// Clone to a bare repository
$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch');

// Clone to a non-bare repository
$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch', false);
```

--------------------------------

### Specify logger as option on creation

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Specifies a logger as an option on repository creation, then runs a fetch command. This is an alternative to using setLogger.

```php
$logger = new MonologLogger('repository');
$repository = new Repository('/path/foo', ['logger' => $logger]);
$repository->run('fetch', ['--all']);
```

--------------------------------

### Clone a repository from URL with Admin::cloneTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Clones a repository from a URL. Default behavior is to clone into a bare repository; pass false as the third argument to clone into a non-bare repository.

```php
// Clone to a bare repository
$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git');

// Clone to a non-bare repository
$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', false);
```

--------------------------------

### Clone an existing Repository object with cloneTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Shortcut to clone an existing Repository instance. The method is called on the repository object and takes the target path as its only argument.

```php
$new = $repository->cloneTo('/tmp/clone');
```

--------------------------------

### Compute repository size with getSize

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Computes the size of a repository using getSize, which returns the size in kilobytes. This command was only tested with linux.

```php
$size = $repository->getSize();

echo 'Your repository size is '.$size.'KB';
```

--------------------------------

### File class methods

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Lists the methods available on the File class. Includes methods for names, diffs, change type checks, line counts, binary detection, and retrieving changes.

```php
$file->getOldName();
$file->getNewName();
$file->getOldDiff();
$file->getNewDiff();

$file->isCreation();
$file->isDeletion();
$file->isModification();

$file->isRename();
$file->isChangeMode();

$file->getAdditions(); // Number of added lines
$file->getDeletions(); // Number of deleted lines

$file->isBinary(); // Binary files have no "lines"

$file->getChanges(); // See next chapter
```

--------------------------------

### Set Hook as Symlink with setSymlink()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Creates a hook as a symlink to an external file. Throws a LogicException if the hook already exists, or a RuntimeException if symlink creation fails.

```php
$hooks->setSymlink('pre-receive', '/path/to/file-to-link');
```

--------------------------------

### Specify git command with command option

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Specifies a custom git binary path using the 'command' option. Useful when the git binary is not in the default location.

```php
$repository = new Gitonomy\Git\Repository('/tmp/foo', ['command' => '/home/alice/bin/git']); 
```

--------------------------------

### Create and delete branches and tags

Source: https://github.com/gitonomy/gitlib/blob/main/doc/references.md

Create a branch or tag using createBranch or createTag with a commit reference, and delete a branch or tag using the delete method on the reference object.

```php
// create a branch
$references = $repository->getReferences();
$branch     = $references->createBranch('foobar', 'a8b7e4...'); // commit to reference

// create a tag
$references = $repository->getReferences();
$tag        = $references->createTag('0.3', 'a8b7e4...'); // commit to reference

// delete a branch or a tag
$branch->delete();
```

--------------------------------

### Checkout a revision with checkout()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Checkout a revision using the checkout method. The second argument is passed with -b to create a new branch.

```php
// git checkout master
$wc->checkout('master');

// git checkout origin/master -b master
$wc->checkout('origin/master', 'master');
```

--------------------------------

### Admin::mirrorTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Mirrors a repository fully, including all references, to a local path. By default, mirrors as a bare repository; pass false as the third argument to mirror as a non-bare repository.

```APIDOC
## Admin::mirrorTo

### Description
Mirrors a repository fully, including all references, to a local path. By default, mirrors as a bare repository; pass false as the third argument to mirror as a non-bare repository.

### Method
Admin::mirrorTo

### Parameters
- **path** (string) - Required - The local path where the repository will be mirrored.
- **url** (string) - Required - The URL of the repository to mirror.
- **bare** (bool) - Optional - Whether to mirror as a bare repository. Defaults to true.

### Request Example
```php
// Mirror to a bare repository
$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git');

// Mirror to a non-bare repository
$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git', false);
```

### Response
Returns a Repository instance representing the mirrored repository.
```

--------------------------------

### Admin::cloneTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Clones a repository from a URL to a local path. By default, clones as a bare repository; pass false as the third argument to clone as a non-bare repository.

```APIDOC
## Admin::cloneTo

### Description
Clones a repository from a URL to a local path. By default, clones as a bare repository; pass false as the third argument to clone as a non-bare repository.

### Method
Admin::cloneTo

### Parameters
- **path** (string) - Required - The local path where the repository will be cloned.
- **url** (string) - Required - The URL of the repository to clone.
- **bare** (bool) - Optional - Whether to clone as a bare repository. Defaults to true.

### Request Example
```php
// Clone to a bare repository
$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git');

// Clone to a non-bare repository
$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', false);
```

### Response
Returns a Repository instance representing the cloned repository.
```

--------------------------------

### File methods

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Exhaustive list of methods available on the File class to inspect file changes.

```APIDOC
## File methods

### Description
Exhaustive list of methods available on the File class to inspect file changes.

### Methods
- `getOldName()` - Returns the old file name.
- `getNewName()` - Returns the new file name.
- `getOldDiff()` - Returns the old diff.
- `getNewDiff()` - Returns the new diff.
- `isCreation()` - Returns true if the file is a creation.
- `isDeletion()` - Returns true if the file is a deletion.
- `isModification()` - Returns true if the file is a modification.
- `isRename()` - Returns true if the file is a rename.
- `isChangeMode()` - Returns true if the file mode changed.
- `getAdditions()` - Returns the number of added lines.
- `getDeletions()` - Returns the number of deleted lines.
- `isBinary()` - Returns true if the file is binary (binary files have no lines).
- `getChanges()` - Returns the list of FileChange objects.

### Example
```php
$file->getOldName();
$file->getNewName();
$file->getOldDiff();
$file->getNewDiff();

$file->isCreation();
$file->isDeletion();
$file->isModification();

$file->isRename();
$file->isChangeMode();

$file->getAdditions(); // Number of added lines
$file->getDeletions(); // Number of deleted lines

$file->isBinary(); // Binary files have no "lines"

$file->getChanges(); // See next chapter
```
```

--------------------------------

### setSymlink

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Creates a symlink for a hook. Throws LogicException if the hook already exists, and RuntimeException if symlink creation fails.

```APIDOC
## setSymlink

### Description
Creates a symlink for a hook. Throws LogicException if the hook already exists, and RuntimeException if symlink creation fails.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The name of the hook (e.g., 'pre-receive').
- **target** (string) - Required - The path to the file to link.

### Request Example
```php
$hooks->setSymlink('pre-receive', '/path/to/file-to-link');
```

### Response
#### Success Response
No return value.

### Errors
- **LogicException** - Thrown if the hook already exists.
- **RuntimeException** - Thrown if an error occurs during symlink creation.
```

--------------------------------

### Repository::cloneTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Clones an existing Repository instance to a new location.

```APIDOC
## Repository::cloneTo

### Description
Clones an existing Repository instance to a new location.

### Method
Repository::cloneTo

### Parameters
- **path** (string) - Required - The local path where the repository will be cloned.

### Request Example
```php
$new = $repository->cloneTo('/tmp/clone');
```

### Response
Returns a new Repository instance representing the cloned repository.
```

--------------------------------

### getContent

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blob.md

Returns the raw content of the blob.

```APIDOC
## getContent

### Description
Returns the raw content of the blob.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
echo $blob->getContent();
```

### Response
Returns the content of the blob as a string.

```

--------------------------------

### Test if repository is bare

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Calls the isBare method on a Repository object to test if the repository is bare.

```php
$repository->isBare();
```

--------------------------------

### Iterate over file changes

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Iterates over FileChange objects from a file's getChanges() method. For each change, it iterates over lines and prints them with a prefix based on the line type (context, addition, or deletion).

```php
$changes = $file->getChanges();
foreach ($changes as $change) {
    foreach ($lines as $data) {
        list ($type, $line) = $data;
        if ($type === FileChange::LINE_CONTEXT) {
            echo ' '.$line.PHP_EOL;
        } elseif ($type === FileChange::LINE_ADD) {
            echo '+'.$line.PHP_EOL;
        } else {
            echo '-'.$line.PHP_EOL;
        }
    }
}
```

--------------------------------

### Add gitlib dependency to composer.json

Source: https://github.com/gitonomy/gitlib/blob/main/README.md

Add gitlib to your composer.json file manually. This specifies the dependency version ^1.3, which is the alternative to using the composer require command.

```json
{
    "require": {
        "gitonomy/gitlib": "^1.3"
    }
}

```

--------------------------------

### checkout

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Checkout a revision in the working copy. Optionally specify a branch name to create with -b.

```APIDOC
## checkout

### Description
Checkout a revision in the working copy. Optionally specify a branch name to create with -b.

### Method
checkout

### Parameters
- **revision** (string|Reference|Commit) - Required - The revision to checkout. Can be a branch name, tag, commit hash, or a Reference/Commit object.
- **branch** (string) - Optional - If provided, the checkout will create a new branch with this name using `-b`.

### Example
php
// git checkout master
$wc->checkout('master');

// git checkout origin/master -b master
$wc->checkout('origin/master', 'master');

```

--------------------------------

### Iterate over diff files

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Iterates over the files in a Diff object using getFiles(), which returns File objects. For each file, it prints the old and new names along with their modes.

```php
$files = $diff->getFiles();
echo sprintf('%s files modified%s', count($files), PHP_EOL);

foreach ($files as $fileDiff) {
    echo sprintf('Old name: (%s) %s%s', $fileDiff->getOldMode(), $fileDiff->getOldName(), PHP_EOL);
    echo sprintf('New name: (%s) %s%s', $fileDiff->getNewMode(), $fileDiff->getNewName(), PHP_EOL);
}
```

--------------------------------

### File::getChanges

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Returns the list of FileChange objects associated with the file.

```APIDOC
## File::getChanges

### Description
Returns the list of FileChange objects associated with the file.

### Method
PHP method

### Signature
`$file->getChanges()`

### Example
```php
$changes = $file->getChanges();
foreach ($changes as $change) {
    foreach ($lines as $data) {
        list ($type, $line) = $data;
        if ($type === FileChange::LINE_CONTEXT) {
            echo ' '.$line.PHP_EOL;
        } elseif ($type === FileChange::LINE_ADD) {
            echo '+'.$line.PHP_EOL;
        } else {
            echo '-'.$line.PHP_EOL;
        }
    }
}
```

### Returns
An array of FileChange objects.
```

--------------------------------

### Admin::cloneBranchTo

Source: https://github.com/gitonomy/gitlib/blob/main/doc/admin.md

Clones a repository from a URL and checks out a specific branch. In a non-bare repository, the specified branch will be checked out.

```APIDOC
## Admin::cloneBranchTo

### Description
Clones a repository from a URL and checks out a specific branch. In a non-bare repository, the specified branch will be checked out.

### Method
Admin::cloneBranchTo

### Parameters
- **path** (string) - Required - The local path where the repository will be cloned.
- **url** (string) - Required - The URL of the repository to clone.
- **branch** (string) - Required - The branch to check out.
- **bare** (bool) - Optional - Whether to clone as a bare repository. Defaults to true.

### Request Example
```php
// Clone to a bare repository
$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch');

// Clone to a non-bare repository
$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch', false);
```

### Response
Returns a Repository instance representing the cloned repository.
```

--------------------------------

### getBlame

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blame.md

Retrieves a blame object for a given branch and file. The blame object allows iteration over lines and access to commit information.

```APIDOC
## getBlame

### Description
Retrieves a blame object for a given branch and file. The blame object allows iteration over lines and access to commit information.

### Method
PHP method

### Endpoint
$repository->getBlame('master', 'README.md')

### Parameters
- **branch** (string) - Required - The branch name.
- **file** (string) - Required - The file path.

### Request Example
```php
$blame = $repository->getBlame('master', 'README.md');
```

### Response
#### Success Response
Returns a Blame object.

#### Response Example
```php
$blame = $repository->getBlame('master', 'README.md');
```
```

--------------------------------

### getLog

Source: https://github.com/gitonomy/gitlib/blob/main/doc/revision.md

Returns a Log object for the revision, with optional offset and limit parameters.

```APIDOC
## getLog

### Description
Returns a Log object for the revision, allowing retrieval of commit history with offset and limit.

### Method
PHP method

### Endpoint
$revision->getLog($offset, $limit)

### Parameters
- **$offset** (int|null) - Optional - The number of commits to skip. Use null for no offset.
- **$limit** (int|null) - Optional - The maximum number of commits to return. Use null for no limit.

### Request Example
```php
// Returns 100 lasts commits
$log = $revision->getLog(null, 100);
```

### Response
Returns a Log object.

```

--------------------------------

### getLog

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Retrieves a Log object from a repository. Accepts optional branch, paths, offset, and limit parameters to filter the log.

```APIDOC
## getLog

### Description
Retrieves a Log object from a repository. Accepts optional branch, paths, offset, and limit parameters to filter the log.

### Method
Repository::getLog

### Parameters
- **branch** (string) - Optional - Branch name to filter the log.
- **paths** (string|array) - Optional - File path(s) to filter commits affecting those files.
- **offset** (int) - Optional - Number of commits to skip.
- **limit** (int) - Optional - Maximum number of commits to return.

### Request Example
```php
$log = $repository->getLog('master', ['README', 'UPGRADE'], 0, 10);
```

### Response
Returns a Log object representing the commit history.
```

--------------------------------

### getLine

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blame.md

Accesses a specific line by its line number.

```APIDOC
## getLine

### Description
Accesses a specific line by its line number.

### Method
PHP method

### Endpoint
$blame->getLine(32)

### Parameters
- **lineNumber** (int) - Required - The line number to retrieve.

### Request Example
```php
$line = $blame->getLine(32);
```

### Response
#### Success Response
Returns a Line object.

#### Response Example
```php
$line = $blame->getLine(32);
```
```

--------------------------------

### Access HEAD with getHead and getHeadCommit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/repository.md

Accesses the HEAD of the repository. getHead returns a Commit or Reference, getHeadCommit returns a Commit, and isHeadDetached checks if HEAD is detached.

```php
$head = $repository->getHead(); // Commit or Reference
$head = $repository->getHeadCommit(); // Commit

if ($repository->isHeadDetached()) {
    echo 'Sorry man'.PHP_EOL;
}
```

--------------------------------

### getLimit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Returns the current limit value of the log.

```APIDOC
## getLimit

### Description
Returns the current limit value of the log.

### Method
Log::getLimit

### Parameters
None

### Request Example
```php
$limit = $log->getLimit();
```

### Response
Returns an integer representing the current limit.
```

--------------------------------

### getHooks

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Retrieves the Hooks object from a Repository instance.

```APIDOC
## getHooks

### Description
Returns the Hooks object for a repository, allowing management of Git hooks.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **repository** (Repository) - Required - The repository object on which to call this method.

### Request Example
```php
$hooks = $repository->getHooks();
```

### Response
#### Success Response
- **Hooks** (Hooks) - The Hooks object for the repository.

#### Response Example
```php
$hooks = $repository->getHooks();
```
```

--------------------------------

### Diff::getFiles

Source: https://github.com/gitonomy/gitlib/blob/main/doc/diff.md

Returns a list of File objects representing modifications for each file in the diff.

```APIDOC
## Diff::getFiles

### Description
Returns a list of File objects representing modifications for each file in the diff.

### Method
PHP method

### Signature
`$diff->getFiles()`

### Example
```php
$files = $diff->getFiles();
echo sprintf('%s files modified%s', count($files), PHP_EOL);

foreach ($files as $fileDiff) {
    echo sprintf('Old name: (%s) %s%s', $fileDiff->getOldMode(), $fileDiff->getOldName(), PHP_EOL);
    echo sprintf('New name: (%s) %s%s', $fileDiff->getNewMode(), $fileDiff->getNewName(), PHP_EOL);
}
```

### Returns
An array of File objects.
```

--------------------------------

### Recursively display tree entries

Source: https://github.com/gitonomy/gitlib/blob/main/doc/tree.md

Recursively displays all entries of a tree using the getEntries method. Each entry is an array containing the mode and the entry object; directories are shown with a trailing slash and indented.

```php
function displayTree(Tree $tree, $indent = 0)
{
    $indent = str_repeat(' ', $indent);
    foreach ($tree->getEntries() as $name => $data) {
        list($mode, $entry) = $data;
        if ($entry instanceof Tree) {
            echo $indent.$name.'/'.PHP_EOL;
            displayTree($tree, $indent + 1);
        } else {
            echo $indent.$name.PHP_EOL;
        }
    }
}

displayTree($commit->getTree());
```

--------------------------------

### has

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Checks if a hook is present in the repository.

```APIDOC
## has

### Description
Checks if a hook is present in the repository.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The name of the hook (e.g., 'pre-receive').

### Request Example
```php
$hooks->has('pre-receive');
```

### Response
#### Success Response
- **boolean** (bool) - True if the hook exists, false otherwise.

#### Response Example
```php
$hooks->has('pre-receive'); // a boolean indicating presence
```
```

--------------------------------

### getMessage

Source: https://github.com/gitonomy/gitlib/blob/main/doc/commit.md

Returns the full commit message.

```APIDOC
## getMessage

### Description
Returns the full commit message.

### Method
Commit::getMessage

### Parameters
None

### Request Example
```php
$commit->getMessage();
```

### Response
Returns a string.
```

--------------------------------

### getMimetype

Source: https://github.com/gitonomy/gitlib/blob/main/doc/blob.md

Returns the mimetype of the blob using the finfo extension.

```APIDOC
## getMimetype

### Description
Returns the mimetype of the blob using the finfo extension.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
echo $blob->getMimetype();
```

### Response
Returns the mimetype as a string.

```

--------------------------------

### getOffset

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Returns the current offset value of the log.

```APIDOC
## getOffset

### Description
Returns the current offset value of the log.

### Method
Log::getOffset

### Parameters
None

### Request Example
```php
$offset = $log->getOffset();
```

### Response
Returns an integer representing the current offset.
```

--------------------------------

### Check Hook Existence with has()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/hooks.md

Checks whether a hook is present, returning a boolean.

```php
$hooks->has('pre-receive'); // a boolean indicating presence
```

--------------------------------

### setOffset

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Sets the offset for the log, determining how many commits to skip from the beginning.

```APIDOC
## setOffset

### Description
Sets the offset for the log, determining how many commits to skip from the beginning.

### Method
Log::setOffset

### Parameters
- **offset** (int) - Required - The number of commits to skip.

### Request Example
```php
$log->setOffset(32);
```

### Response
No return value.
```

--------------------------------

### setLimit

Source: https://github.com/gitonomy/gitlib/blob/main/doc/log.md

Sets the maximum number of commits to return from the log.

```APIDOC
## setLimit

### Description
Sets the maximum number of commits to return from the log.

### Method
Log::setLimit

### Parameters
- **limit** (int) - Required - The maximum number of commits to return.

### Request Example
```php
$log->setLimit(40);
```

### Response
No return value.
```

--------------------------------

### Merge a revision with merge()

Source: https://github.com/gitonomy/gitlib/blob/main/doc/workingcopy.md

Merge a revision into the current branch using the merge method. The second argument passes extra options to git merge. A RuntimeException is thrown if the merge fails.

```php
// git merge origin/develop
$wc->merge('origin/develop');

// git merge --no-ff origin/develop
$wc->merge('origin/develop', ['--no-ff']);
```
Tokens:
Raw