Skip to content

installation.md

Latest commit

 

History

History
271 lines (202 loc) · 11.4 KB

installation.md

File metadata and controls

271 lines (202 loc) · 11.4 KB
Raw

Installation

Pointbreak Review publishes prebuilt pointbreak binaries for macOS, Linux, and Windows. The install scripts select the archive for the current platform and verify it against the release's checksums.txt before writing the binary.

macOS and Linux

Install the latest release into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.sh | sh

If ~/.local/bin is not already in PATH, the installer prints a command for your current shell and names the appropriate zsh or bash configuration file for a permanent change. Run the command, then verify the result:

pointbreak --version

The script also supports wget when run from a local checkout.

Pin a version or change the install directory

Pass installer options after sh -s --:

curl -fsSL https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.sh \
  | sh -s -- --version=v0.7.0 --prefix="$HOME/bin"

--version accepts a release with or without its leading v. The default is the latest published, non-prerelease GitHub release. --prefix names the directory that will contain pointbreak.

Windows PowerShell

Install the latest release into %LOCALAPPDATA%\Pointbreak\bin:

irm https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.ps1 | iex

The installer adds that directory to your user PATH when necessary. Restart the terminal before running:

pointbreak --version

To pin a version, choose another install directory, or leave PATH unchanged, invoke the downloaded script as a script block:

$Install = [scriptblock]::Create((irm https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.ps1))
& $Install -Version v0.7.0 -InstallDir "$HOME\bin" -NoModifyPath

Your first Review

Once pointbreak --version reports the installed release, go straight to a first useful Review: make a real change to a tracked file in one of your repositories, capture it with a useful summary, and open Review:

pointbreak capture --summary "<what changed>"
pointbreak inspect --open

Getting started continues from here through the complete paired author/reviewer loop. The sections below cover installer options, checksum verification, supported platforms, and manual downloads; return to them when you need them.

Derived access after upgrade

Current Pointbreak builds enable the private sqlite-wal-bodyless-v1 derived-access profile when POINTBREAK_DERIVED_ACCESS is unset. Loose Journal and ContentStore bytes remain the sole authority; the SQLite state is bodyless, disposable, and rebuildable. Set POINTBREAK_DERIVED_ACCESS=off for immediate, artifact-free rollback before starting Pointbreak. This is also the safe runtime posture before temporarily using an older binary that does not understand the current derived layout.

The stable derived/ container lives directly beneath the exact resolved authoritative store root. A clone-local, ephemeral, or user-level family store therefore owns its corresponding sidecar. An existing legacy .pointbreak-derived/ namespace remains readable and is moved to the stable namespace only when its generation and sibling lock/lease state can transition safely; the move does not replay or rewrite truth.

Use the lifecycle commands against the repository whose store you intend to inspect:

pointbreak store derived status --repo <path>
pointbreak store derived build --repo <path>
pointbreak store derived rebuild --repo <path>

status is read-only. build synchronously creates or repairs a generation only when needed, while rebuild always stages and publishes a replacement generation. Build and rebuild may scan the complete event history, so they can take substantial time on a large store; cancellation or failure preserves loose truth and any previously valid generation.

If both derived/ and the legacy namespace exist, text status identifies both local paths. Inspect them, retain one disposable copy and move the other aside, then retry. Pointbreak never chooses, merges, deletes, or labels either copy authoritative. If derived state is absent or unavailable, bounded CLI reads fall back to loose truth with one actionable hint, writes still publish loose truth, and Inspector can build in the background.

The rollout and lifecycle have native qualification on macOS/APFS and Windows/NTFS. Linux remains covered by the normal compile and CI lanes; retained-scale Linux behavior has not been separately measured.

Windows: the NTFS change journal

On Windows, derived acceleration needs an active NTFS USN change journal on the volume that holds the store. The journal is how Pointbreak proves that nothing changed its authoritative events/ directory since the derived generation last caught up. System volumes such as C: normally have a journal. Secondary, removable, and ephemeral volumes may not, for example a cloud VM's temporary disk.

What Pointbreak reads, and only reads:

  • It makes two read-only control calls, FSCTL_QUERY_USN_JOURNAL for the journal's identity and position and FSCTL_READ_UNPRIVILEGED_USN_JOURNAL for the records since its saved position.
  • Both go through a read-only handle to the volume's root directory opened with backup semantics, not raw volume access. Neither call needs administrator rights.
  • Each check reads at most 1 MiB of records. A longer interval is reported as unproven, and the generation is rechecked instead of trusted.
  • The unprivileged read strips file names, so Pointbreak never learns the names of other files on the volume. It matches parent-directory references against its own events/ directory only.
  • Pointbreak never creates, deletes, resizes, or configures a journal.

When the volume has no active journal, derived access is unavailable and every read uses the authoritative path instead. It is not retried, because it lasts until an administrator acts. pointbreak store derived status reports it as "availability": "unavailable" with "reason": "journal_unavailable", and its detail names the volume and both remedies.

To keep acceleration, an administrator creates a journal on that volume. The maximum size and allocation delta are in bytes. Copying the values fsutil usn queryjournal C: reports for the system volume is a reasonable default.

# Elevated PowerShell or Command Prompt
fsutil usn queryjournal D:
fsutil usn createjournal m=<size> a=<delta> D:

Once the journal exists, pointbreak store derived status stops reporting journal_unavailable, even in a process that was already running. Reads keep using the authoritative path until a generation is built, so run pointbreak store derived build to resume acceleration.

To run without the journal instead, turn derived access off:

$env:POINTBREAK_DERIVED_ACCESS = "off"

With derived access off, Pointbreak makes no journal reads at all. Every read uses the authoritative journal and content store, which is slower on large stores but always correct.

Checksum verification

Verification is on by default and fails closed. The installer stops without replacing pointbreak if:

  • checksums.txt cannot be downloaded;
  • the selected archive has no valid entry;
  • SHA-256 tooling is unavailable on macOS or Linux; or
  • the downloaded archive's checksum does not match.

You can bypass verification explicitly with --no-verify on macOS or Linux, or -NoVerify on Windows. This is intended for exceptional situations where you have verified the archive another way.

To inspect a script before running it:

curl -fsSL -o install.sh https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.sh
less install.sh
sh install.sh

On Windows:

irm https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.ps1 -OutFile install.ps1
Get-Content .\install.ps1
.\install.ps1

Install with Cargo

The published crate is named pointbreak and installs the pointbreak command:

cargo install pointbreak
pointbreak --version

This path builds from source and requires a current Rust toolchain. The release installers do not.

Upgrading to 0.7.0

Release 0.7.0 is a one-release hard cutover. Before its first use:

  1. Stop every process that can write Review state.

  2. Move owner-controlled state and config offline, preserving the directory contents:

    pre-0.7.0 operational location 0.7.0 location
    <repo>/.shore/ <repo>/.pointbreak/
    <git-common-dir>/shore/ <git-common-dir>/pointbreak/
    <git-common-dir>/shore.link.json <git-common-dir>/pointbreak.link.json
    $XDG_DATA_HOME/shore $XDG_DATA_HOME/pointbreak
    $HOME/.shore $HOME/.pointbreak
    %APPDATA%\shore %APPDATA%\pointbreak

    Move a linked clone's shared common-directory store once, not once per worktree. If you set an explicit user home, move that directory to the location now selected by POINTBREAK_HOME.

  3. Update environment and configuration references to the canonical POINTBREAK_* names and Pointbreak paths.

  4. Run pointbreak store paths --repo <path> --format json to confirm the canonical repository, common-directory, binding, home, and key locations, then verify readback with commands such as pointbreak revision list and pointbreak history.

Rollback is the inverse filesystem move performed while writers remain stopped. Pointbreak provides no runtime fallback, compatibility alias, automatic migration, migration CLI, or dual read/write window. The reserved pointbreak store migrate syntax describes an older Pointbreak store-topology change; it does not perform this 0.7.0 namespace cutover and is fail-closed while exact Change store transfer is unavailable.

Supported platforms

Target Operating system Architecture Archive
darwin-x64 macOS Intel 64-bit .tar.gz
darwin-arm64 macOS Apple silicon .tar.gz
linux-x64 Linux (glibc) x86-64 .tar.gz
linux-arm64 Linux (glibc) ARM64 .tar.gz
alpine-x64 Linux (musl/Alpine) x86-64 .tar.gz
alpine-arm64 Linux (musl/Alpine) ARM64 .tar.gz
win32-x64 Windows x86-64 .zip
win32-arm64 Windows ARM64 .zip

The macOS/Linux installer requires tar, plus either curl or wget, and either sha256sum or the macOS-provided shasum. The Windows installer uses built-in PowerShell archive and hashing commands.

Manual download

Download the archive for your target and checksums.txt from the GitHub releases page. For example, on Apple silicon macOS:

VERSION=0.7.0
TARGET=darwin-arm64
ARCHIVE="pointbreak-${VERSION}-${TARGET}.tar.gz"
BASE="https://github.com/withpointbreak/pointbreak/releases/download/v${VERSION}"

curl -fsSLO "${BASE}/${ARCHIVE}"
curl -fsSLO "${BASE}/checksums.txt"
grep "  ${ARCHIVE}$" checksums.txt | shasum -a 256 -c -
tar -xzf "$ARCHIVE"
install -m 0755 pointbreak "$HOME/.local/bin/pointbreak"

On Linux, replace shasum -a 256 with sha256sum. Windows archives contain pointbreak.exe and can be verified with Get-FileHash -Algorithm SHA256 before using Expand-Archive.

Archives downloaded with curl on macOS normally need no quarantine adjustment. If a browser adds the quarantine attribute, remove it from the extracted binary with:

xattr -d com.apple.quarantine ./pointbreak