Ga naar de inhoud

Mergen

Bekijken als Markdown Bewerken op GitHub Documentatie op bfe242f

Pitmaster voert branch-merges uit met een three-way merge, net als git merge. Het detecteert mogelijkheden voor fast-forward, berekent mergebasissen, voert merges op tree- en inhoudsniveau uit en genereert standaardconflictmarkeringen wanneer bestanden conflicteren.

Eenvoudige merge

PHP
$result = $repo->merge('feature/login');

if ($result->clean) {
    echo "Merged successfully: {$result->commitId->hex}\n";
} else {
    echo "Conflicts:\n";
    foreach ($result->conflictPaths as $path) {
        echo "  {$path}\n";
    }
}

MergeResult

De klasse MergeResult is een alleen-lezen value object:

PHP
use Pitmaster\Merge\MergeResult;

$result->clean;           // bool: true if merge completed without conflicts
$result->commitId;        // ?ObjectId: the merge commit (null if conflicts)
$result->conflictPaths;   // array: list of file paths with conflicts
$result->mergedContents;  // array: path => content with conflict markers (if conflicts)

Wanneer de merge stopt vanwege conflicten, wordt de conflictstatus naar de index en de werkboom geschreven. Los de bestanden op, add() ze en roep $repo->mergeContinue() aan, of roep $repo->mergeAbort() aan om de status van vóór de merge te herstellen.

Commit of stash lokale wijzigingen voordat u gaat mergen: de merge bouwt de werkboom opnieuw op aan de hand van het resultaat en overschrijft niet-vastgelegde wijzigingen in bijgehouden bestanden (#2).

Fast-forward-merges

Wanneer de huidige HEAD een voorouder is van de doelbranch, voert Pitmaster een fast-forward-merge uit: het verplaatst HEAD simpelweg naar de doelcommit zonder een mergecommit aan te maken.

Code
Before:         After fast-forward:

A---B (main)    A---B---C---D (main)
     \
      C---D (feature)
PHP
$result = $repo->merge('feature');
// $result->clean === true
// $result->commitId points to D
// No merge commit created

Het omgekeerde geval wordt nog niet gedetecteerd: een branch mergen die HEAD al bevat, maakt een nieuwe mergecommit met een ongewijzigde tree in plaats van "Already up to date" te melden (#6).

Drieweg-samenvoeging

Wanneer branches uiteen zijn gelopen, voert Pitmaster een three-way merge uit:

  1. Zoek de mergebasis (laagste gemeenschappelijke voorouder)
  2. Vergelijk de tree van de basis met die van ons en die van hen
  3. Voer voor elk bestand dat in beide branches is gewijzigd een merge op inhoudsniveau uit
  4. Maak een mergecommit met twee ouders
Code
Before:              After merge:

      C---D (feature)         C---D
     /                       /     \
A---B---E---F (main)   A---B---E---F---G (main)

Mergebasis

De mergebasis is de meest recente gemeenschappelijke voorouder van twee commits. Pitmaster vindt deze door de commitgraaf te doorlopen. Als er meerdere mergebasissen zijn (criss-cross-geschiedenis), voegt merge() die eerst samen en gebruikt het resultaat als basis.

PHP
$base = $repo->mergeBase(
    $repo->resolve('main'),
    $repo->resolve('feature/login'),
);

if ($base !== null) {
    echo "Common ancestor: {$base->hex}\n";
}

Voor directe toegang tot het algoritme van MergeBase:

PHP
use Pitmaster\Merge\MergeBase;

$finder = new MergeBase($repo->objectDatabase());
$base = $finder->find($commitA, $commitB);

// All merge bases (criss-cross histories can have more than one)
$bases = $finder->findAll($commitA, $commitB);

// Check ancestry
$isAncestor = $finder->isAncestor($oldCommit, $newCommit);

Branch-mergecontrole

PHP
if ($repo->isBranchMerged('feature/done')) {
    // All commits in feature/done are reachable from default branch
    $repo->deleteBranch('feature/done');
}

// Check against a specific target
if ($repo->isBranchMerged('feature/done', 'develop')) {
    // Merged into develop
}

Conflictmarkeringen

Wanneer een bestand in beide branches is gewijzigd en de wijzigingen elkaar overlappen, genereert Pitmaster standaardconflictmarkeringen. merge() labelt de kanten met HEAD en de naam van de samengevoegde branch:

Code
<<<<<<< HEAD
    return $this->value + 1;
=======
    return $this->value * 2;
>>>>>>> feature

De klasse ConflictMarker plaatst twee versies tussen markeringen:

PHP
use Pitmaster\Merge\ConflictMarker;

$marked = ConflictMarker::mark($oursContent, $theirsContent, 'HEAD', 'feature');

// diff3 style, with the base section
$marked = ConflictMarker::mark($oursContent, $theirsContent, 'HEAD', 'feature', $baseContent, 'base');

Three-way merge op inhoudsniveau

De klasse ThreeWayMerge voegt blob-inhoud samen (geen bestanden):

PHP
use Pitmaster\Merge\ThreeWayMerge;

$result = ThreeWayMerge::merge($baseContent, $oursContent, $theirsContent, 'HEAD', 'feature');

$result['content'];   // merged text, with conflict markers if needed
$result['clean'];     // true when nothing conflicted
$result['conflicts']; // number of conflict regions

Deze neemt drie strings (de basisversie, onze versie en hun versie), plus optionele labels en een conflictstijl (standaard 'merge', of 'diff3' om het basisgedeelte op te nemen).

Mergestrategieën

Recursieve merge

De standaardstrategie ($repo->merge($branch)) verwerkt criss-cross-mergegeschiedenissen met meerdere mergebasissen. De CLI accepteert hiervoor ook -s ort en -s recursive.

Ours-merge

Legt een mergecommit vast die de tree van HEAD ongewijzigd laat. Handig om de branchgeschiedenis bij te houden zonder wijzigingen op te nemen.

PHP
$result = $repo->merge('feature/old', 'ours');

Octopus-merge

Voegt twee of meer branches samen in één mergecommit. Als een branch conflicten oplevert, retourneert deze een niet-schone uitkomst zonder de mergestatus op te slaan of een commit aan te maken.

PHP
$result = $repo->mergeOctopus(['feature/a', 'feature/b', 'feature/c']);

De klassen RecursiveMerge, OursMerge en OctopusMerge in Pitmaster\Merge zijn helpers voor merges op inhoudsniveau; Repository implementeert de bovenstaande strategieën zelf.

Rerere (opgeslagen oplossing opnieuw gebruiken)

Pitmaster bevat een zelfstandige klasse Rerere die oplossingen opslaat in de rr-cache-indeling van git:

PHP
use Pitmaster\Merge\Rerere;

$rerere = new Rerere($repo->gitDir());

if ($rerere->isEnabled()) {                     // rerere.enabled = true in .git/config
    $rerere->record($conflicted, $resolved);    // remember a resolution
    $resolved = $rerere->resolve($conflicted);  // replay it, or null
}

merge() roept deze niet aan: oplossingen worden alleen vastgelegd en opnieuw afgespeeld wanneer uw code dat doet. isEnabled() zoekt naar de letterlijke tekst rerere.enabled = true in .git/config en herkent het gedeelte [rerere] niet dat git config rerere.enabled true schrijft (#20).

Mergeverloop op tree-niveau

Het volledige mergeproces:

  1. MergeBase::findAll() zoekt de gemeenschappelijke voorouders
  2. De trees van de basis, ons en hen worden pad voor pad vergeleken
  3. Voor bestanden die slechts in één branch zijn gewijzigd: neem die wijziging over
  4. Voor bestanden die in beide branches zijn gewijzigd:
    • Als beide op dezelfde manier zijn gewijzigd: neem een van beide (ze komen overeen)
    • Als de wijzigingen verschillen: voer ThreeWayMerge::merge() uit op de inhoud
  5. Als alle merges zonder conflicten verlopen: bouw de samengevoegde tree op en maak een mergecommit
  6. Bij conflicten: retourneer MergeResult met clean = false en de conflictpaden

Gebruik van CLI

Shell
./vendor/bin/pitmaster merge feature/login

Uitvoer bij succes:

Code
Merge successful.

Uitvoer bij conflict:

Code
CONFLICT in: src/File.php, src/Other.php