Crate devset_core

Expand description

Versioned file bundles, applied to a directory and updated without losing local edits.

A profile is a directory of files in a source, a git repository or a local directory; a target is a directory that names its sources and applies profiles from them as layers. Profiles compose as crates do: a profile requires others by name, and offers features that add files, parts, requirements and features of what it requires; an entry applies only when its gates hold. devset records what it wrote in the target’s .devset/, so a later update tells a local edit from a change the profile made: the edit is kept, and merged with the change where the file’s Policy says so. A profile owns a whole file, or a part of one its Scope names: the keys its payload defines, or a marked block.

§Applying a profile

Every operation is a prefix of one chain, and only commit writes:

use std::fs;

use devset_core::source::Source;
use devset_core::target::LayerSpec;
use devset_core::{Cache, Mode, Refresh, Target, commit, plan, resolve, survey};

let dir = camino_tempfile::tempdir()?;
let root = dir.path();
let mut target = Target::open_or_new(&root.join("repo"))?;
target.add_source("house".parse()?, Source::Dir("../house".into()))?;
target.add_layer(LayerSpec::new("house/base".parse()?))?;

let resolved = resolve(&target, &Cache::at(root.join("cache")), Refresh::None)?; // read, compose
let survey = survey(resolved, &target)?; // compare with the disk
let plan = plan(survey, Mode::Apply, &target)?; // decide, merge
commit(plan, &target)?; // write, state last

let applied = fs::read_to_string(root.join("repo/.editorconfig"))?;
assert_eq!(applied, "root = true\n", "the profile's file, in the target");

§Updating

Refresh::All moves every source to what its ref names now; the rest of the chain is the same. A merge file then merges its local edits with the profile’s new version. A conflict leaves the run unfinished, waiting in .devset/conflicts/: a chain under Mode::Continue installs the fix, or a Rollback takes the whole run back.

§Types

Target: the directory devset manages, and what its .devset/ records.
Resolved: the target’s layers composed, one provider per path.
Survey: every managed path as the profile wants it, as recorded, and as on disk.
Plan: what committing does to each path.
Rollback: an unfinished run, and what taking it back restores.
Error: why any of it did not go through, one type per domain.

The files people write have modules of their own: profile for profile.toml, collection for a source’s profiles, target for .devset/config.toml, and source for where profiles come from; name holds the names they use.

Modules§

collection: A source’s profiles, found by name wherever they are in it, and what collection.toml says of the source.
name: The names profiles, sources, features and scaffolds go by, and source/profile.
plan: Deciding what committing does to each path, merges included.
profile: What a profile declares, in its profile.toml.
resolve: Resolving a target’s layers into one Resolved profile: read, composed, answered, rendered.
source: Where a layer’s profile comes from: a local directory, or a git repository at one commit.
survey: Comparing a target with its resolved profile, path by path.
target: The directory devset manages, and what its .devset/ records.

Structs§

Cache: Fetched git profiles, shared by every target on the machine.
NameError: Why a string is not the name of a profile, a source, a feature or a scaffold.
ParseError: A file that does not parse, with the text to point into.
PathError: Why a string is not a RelPath.
Plan: Everything committing will do; nothing is written until commit.
RelPath: A path a profile manages, relative to the target root.
Resolved: A target’s layers, composed: each file has one provider, or one per part, and settings are decided.
Rollback: An unfinished run, and what taking it back does.
Survey: A target’s managed paths against its resolved profile, in path order.
Target: A directory devset manages.

Enums§

Error: Why a devset operation did not go through.
MergeError: Why a merge cannot run, or its resolution cannot be installed.
Mode: How far a plan may go.
ProfileError: Why a profile, or the layers together, do not resolve.
Refresh: Which sources resolve may move off their locked commit.
Revert: What taking a target file back does.
SourceError: Why a source cannot be read.
TargetError: Why a target cannot be found, read or written.
VarError: Why the layers’ variables cannot be answered or rendered.

Constants§

VERSION: This build’s version, which a profile’s devset requirement is checked against.

Functions§

commit: Carries out plan in target, returning its steps.
plan: Decides every path of survey under mode, running the merges it needs.
resolve: Resolves target’s layers into one profile, the target’s overrides and settings on top.
survey: Compares target’s files with resolved, and settles the gates that depend on them: each scaffold, and each exists.

Type Aliases§

Result: A Result that fails with an Error unless told otherwise.