Sharing styles

Installing styles from a source, pinning them in a project, and contributing one. Formats work the same through rapid format ….

#Adding a style

rapid style add <source> checks a package and installs it in ~/.rapid/styles/<name>/<version>/. It prints the name, version, and canonical hash, then the folder.

rapid style add ./my-style                              # a folder
rapid style add ./my-style-0.1.0.zip                    # a zip
rapid style add https://example.com/my-style.zip        # any https address
rapid style add github:someone/looks/styles/quiet      # a folder in any GitHub repository
rapid style add swiss                                   # styles/swiss in rapid's repository, its default branch
rapid style add swiss@v1.0.0                            # the same folder at a tag, a branch, or a commit

How it reads a source:

• Starting with github: is a GitHub repository.
• Starting with http:// or https:// is an address. Only https is fetched, except from localhost, 127.0.0.1, and [::1].
• A path (starting with ., /, or ~, containing a /, or ending in .zip) is a folder or a zip on disk.
• Anything else is <name>[@ref], the folder styles/<name> of rapid's repository (see by name).

Every package is checked on the way in: its manifest and style.json against their schemas, every file's hash, only allowed file types, and the size limit. Installing the same version again with the same files does nothing; with different files it's refused, since a version never changes.

rapid style list prints what's installed: name, version, the start of its hash, and where it came from.

#From GitHub

github:owner/repo[/path][@ref]

rapid asks GitHub which commit ref is (default HEAD: the default branch), then fetches the repository's archive at that commit. Then:

• with no path, a manifest.json at the root is the package;
• with a path, a manifest.json in that folder is the package;
• otherwise an index.json at the root lists the repository's packages, and the path (or the only entry) picks one by name:

{
  "packages": [
    { "name": "swiss", "path": "styles/swiss", "kind": "style" },
    { "name": "reel", "path": "formats/reel", "kind": "format" }
  ]
}

A tag pins a release: github:owner/repo/styles/swiss@v1.0.0. rapid records the source at its commit, github:owner/repo/styles/swiss@<commit>, so what it installs and pins is exactly those files.

Files a repository keeps in Git LFS (videos, pictures) are pointers in its archive. rapid swaps each pointer in the package for its file, fetched from GitHub's media address at the same commit, and refuses one whose size or hash is not the pointer's.

#By name

A bare name is a folder of rapid's own repository: rapid style add swiss is github:fakeplant/rapid/styles/swiss, and rapid format add reel is github:fakeplant/rapid/formats/reel. After @ comes a tag, a branch, or a commit; without one it's the default branch. A branch with a / in its name needs the full github: form.

To take bare names from another repository laid out the same way (a fork, or a team's own), name it in ~/.rapid/config.json:

{ "styles_repo": "someone/looks" }

Commands that take --style find a built-in style (bubble, conspiracy, launch, poster, swiss, terminal) in your checkout by name without fetching anything; rapid style add <name> always fetches.

#Pinning in a project

rapid style use swiss --project ~/videos/launch
rapid format use reel --project ~/videos/launch

use takes <name>[@ref], installs it if it isn't installed (a built-in format from the checkout, anything else by name from GitHub; a ref that is a version, such as swiss@0.3.0, is found among the installed ones first), and writes its pin to the project's rapid.lock, replacing any earlier pin of that name:

{
  "lock_version": 1,
  "packages": [
    { "kind": "format", "name": "reel", "version": "1.0.0", "sha256": "…", "source": "/path/to/rapid/formats/reel" },
    { "kind": "style", "name": "swiss", "version": "0.1.0", "sha256": "…", "source": "github:fakeplant/rapid/styles/swiss@3f9c…" }
  ]
}

The hash is of the package packed canonically (sorted entries, fixed stamps), not of the bytes as downloaded, so the same files pin the same hash from any source. When a command resolves a pinned package and it isn't installed, rapid fetches it again from source and refuses it if the hash differs. An installed copy that no longer matches its pin is refused too. Commit rapid.lock with your project.

#Contributing a style

A style is shared by adding its folder to rapid's repository with a pull request. Once it's merged, rapid style add <name> installs it anywhere, and the styles page shows it.

1. Fork the repository and add styles/<name>/: manifest.json (its name is the folder's name), style.json, style.css, taste.md, a few reference stills in refs/, and proof/scene.html. See making a style.

2. Render its proof, which also writes the manifest's file list:

   rapid style proof styles/<name>

3. Run the check a pull request has to pass, with the proof required:

   rapid style check styles/<name> --publish

4. Commit with Git LFS installed (git lfs install): the repository's .gitattributes keeps videos and the proof's and refs' pictures in LFS. Open the pull request.

A merged style changes only through another pull request, and a change raises its version: the same version with different files is refused by anyone who already has it.