Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions .vortex/docs/content/updating-vortex.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,10 @@ deployment like any other change:
```

Near the end, the update shows **Finished updating Vortex** with a
reminder to review and commit the changes. When it replaced any of your
changes, it also names `.logs/vortex-update.md`, the file that records
them.
reminder to review and commit the changes. It counts the files per
status and names `.logs/vortex-install-TIMESTAMP.md`, the report that
lists each file with its status. When it replaced any of your changes, it
also names `.logs/vortex-update.md`, the file that records them.

To pin a specific release or commit instead, pass the repository URL with
the reference after `#`:
Expand All @@ -111,6 +112,29 @@ deployment like any other change:
git diff
```

Read the diff alongside `.logs/vortex-install-TIMESTAMP.md`, where
`TIMESTAMP` is the date and time the update ran. Each row of the report
gives a status and a link to the file. When the update changed the file,
the row also links to a diff of that change. The update assigns each file
1 of these statuses:

| Status | What the update did |
|---------------|------------------------------------------------------------------------------|
| `added` | Your project didn't have the file, so the update added it. |
| `updated` | You hadn't changed the file, so the update replaced it with the new version. |
| `unchanged` | The file already matched the new version. |
| `overwritten` | The update replaced a file that held your changes or that it couldn't read. |
| `removed` | The update no longer installs the file, so it removed the file. |
| `kept` | You had changed a file the update no longer installs, so the update kept it. |
| `failed` | The update couldn't write the new version of the file. |

The update writes the diffs to `.logs/vortex-install-TIMESTAMP/`, 1
`.diff` file per changed file, at the file's own path. Each diff runs
from your copy before the update to the copy the update left. Every
`overwritten` file needs your changes re-applied, and its diff shows the
changes the update replaced. A reviewer compares the report with the
final diff to tell a deliberate edit from a missed one.

4. Re-apply your customizations from `.logs/vortex-update.md`, and delete
each entry after you've resolved it. Each entry shows 2 diffs: your
change and the change the new version brings. Each update appends a new
Expand Down
2 changes: 1 addition & 1 deletion .vortex/installer/src/Command/InstallCommand.php
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ function (string $dir, string $ref): void {
return Command::FAILURE;
}

$this->presenter->footer($this->fileManager->getRegistryFile());
$this->presenter->footer($this->fileManager->getRegistryFile(), $this->fileManager->getReportFile(), $this->fileManager->getReportSummary());

$should_build = TRUE;
$requested_build = (bool) $this->config->get(Config::BUILD_NOW);
Expand Down
36 changes: 34 additions & 2 deletions .vortex/installer/src/Prompts/InstallerPresenter.php
Original file line number Diff line number Diff line change
Expand Up @@ -129,14 +129,20 @@ public function header(Artifact $artifact, string $version): void {
* @param string|null $registry_file
* Path of the registry of project changes the update replaced, or NULL
* when the update replaced none.
* @param string|null $report_file
* Path of the report of what the installation did to each template file,
* or NULL when none was written.
* @param array<string, int> $report_summary
* Count of template files per report status.
*/
public function footer(?string $registry_file = NULL): void {
public function footer(?string $registry_file = NULL, ?string $report_file = NULL, array $report_summary = []): void {
$output = '';
$prefix = ' ';

if ($this->config->isVortexProject()) {
$title = 'Finished updating Vortex';
$output .= 'Please review the changes and commit the required files.';
$output .= $this->renderReport($report_file, $report_summary);

if ($registry_file !== NULL) {
$output .= PHP_EOL . PHP_EOL;
Expand All @@ -159,12 +165,38 @@ public function footer(?string $registry_file = NULL): void {

$output .= 'Add and commit all files:' . PHP_EOL;
$output .= $prefix . 'git add -A' . PHP_EOL;
$output .= $prefix . 'git commit -m "Initial commit."' . PHP_EOL;
$output .= $prefix . 'git commit -m "Initial commit."';
$output .= $this->renderReport($report_file, $report_summary) . PHP_EOL;
}

Tui::box($output, $title);
}

/**
* Render the count of files per status and the path of the report.
*
* @param string|null $report_file
* Path of the report, or NULL when none was written.
* @param array<string, int> $report_summary
* Count of template files per report status.
*
* @return string
* The rendered lines, prefixed with a blank line, or an empty string.
*/
protected function renderReport(?string $report_file, array $report_summary): string {
if ($report_file === NULL) {
return '';
}

$counts = array_map(fn(string $status, int $count): string => sprintf('%d %s', $count, $status), array_keys($report_summary), $report_summary);

$output = PHP_EOL . PHP_EOL;
$output .= 'Files: ' . implode(', ', $counts) . PHP_EOL;
$output .= 'Status and diff of every file are recorded in:' . PHP_EOL;

return $output . ' ' . File::toRelative($report_file, (string) $this->config->getDestination());
}

/**
* Display footer after build succeeded.
*/
Expand Down
69 changes: 69 additions & 0 deletions .vortex/installer/src/Utils/Diff.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<?php

declare(strict_types=1);

namespace DrevOps\VortexInstaller\Utils;

use SebastianBergmann\Diff\Differ;
use SebastianBergmann\Diff\Output\StrictUnifiedDiffOutputBuilder;

/**
* Unified diffs of file content.
*/
class Diff {

/**
* Largest content, in bytes, that is rendered as a diff.
*/
const MAX_BYTES = 102400;

const SKIP_BINARY = 'binary';

const SKIP_TOO_LARGE = 'too large';

/**
* Render a unified diff between 2 versions of content.
*
* @param string $from
* Content to diff from.
* @param string $to
* Content to diff to.
* @param string $from_label
* Label for the left side.
* @param string $to_label
* Label for the right side.
*
* @return string
* The diff with its header, without a trailing newline.
*/
public static function unified(string $from, string $to, string $from_label, string $to_label): string {
// Numbered hunks let editors and 'git apply' locate each change.
$differ = new Differ(new StrictUnifiedDiffOutputBuilder(['fromFile' => $from_label, 'toFile' => $to_label]));

return rtrim($differ->diff($from, $to));
}

/**
* Find why content cannot be rendered as a diff.
*
* @param string ...$sides
* Every version of the content.
*
* @return string|null
* One of the SKIP_* constants, or NULL when the content can be diffed.
*/
public static function skipReason(string ...$sides): ?string {
foreach ($sides as $side) {
if (str_contains($side, "\0")) {
return self::SKIP_BINARY;
}

if (strlen($side) > self::MAX_BYTES) {
return self::SKIP_TOO_LARGE;
}
}

return NULL;
}

}
Loading
Loading