Getting Started

This tutorial applies a first profile to a repository, and shows how devset treats an edit to a file it manages.

Install

Install has every way to install devset; the shortest:

curl --proto '=https' --tlsv1.2 -fsSL https://atomix-labs.github.io/devset/install.sh | sh

A First Target

A target is a directory devset manages. devset init makes one, in the directory you name, created if missing, or in the one you are in:

$ devset init hello
     Created hello/.devset/config.toml
help: add a layer: `devset add <source>/<profile> --git <url>`, or `--path <dir>`

.devset/config.toml starts as a commented skeleton: where profiles come from, and which to apply. init runs no git and needs no source; a target with no layer is a target all the same. At a git repository’s top level, or in an empty directory, init can wait: the first devset add starts the target itself.

A First Profile

A profile is a directory holding profile.toml, which lists the files it manages, and files/, which holds them as the target should have them. Profiles live in a source, a directory of them; make one beside a repository:

profiles/
  base/
    profile.toml
    files/
      .editorconfig
      rustfmt.toml

# profiles/base/profile.toml
[profile]
name = "base"

[files.".editorconfig"]

[files."rustfmt.toml"]
policy = "merge"

devset init <dir> --profile writes a profile’s skeleton, its manifest a commented tour of what it can say. Then, in the repository, add it as a layer, naming the source house:

$ devset add house/base --path ../profiles
     Created .editorconfig
     Created rustfmt.toml
    Finished 2 changes

devset named the source in .devset/config.toml, applied house/base, and recorded what it wrote in .devset/. Commit .devset/ with the files: it is what lets a teammate, or CI, see the same thing.

[sources]
house = { path = "../profiles" }

[[layers]]
profile = "house/base"

Where Things Stand

devset status compares every managed file with the profile, and says what would change it:

$ devset status
house/base

All 2 files match the profile.

Edit both files, and ask again:

$ devset status
house/base

Drifted — `devset apply --force` restores:
    edited     .editorconfig  owned  restore

Local changes, kept:
    edited     rustfmt.toml   merge

.editorconfig has the default policy, owned: the profile is authoritative, and the edit is drift. devset apply still leaves it alone, since devset never destroys an edit unless told to; devset apply --force restores it. rustfmt.toml is merge: the edit is the repository’s, kept, and merged with the profile’s own changes when the profile changes.

A file whose only change is whitespace at the end of its lines or of the file, its line endings or a BOM is cosmetic, not edited: an editor that trims whitespace or converts line endings never makes drift.

A Source in Git

A team keeps its profiles in a git repository, and a target pins a tag of it:

devset add acme/rust --git https://github.com/acme/profiles --tag v1.4.0 --features docs
devset add acme/book                       # the source is named now: a name is enough

.devset/lock.toml records the commit the tag named. Every later apply, on any machine, uses that commit; devset update moves to what the tag, or a branch, names now, and merges your edits with what changed. devset list acme shows every profile the source holds, and its features.

Show It

A repository devset manages may say so in its README, with this badge, which atxp’s project profile adds to the header with its feature devset-badge:

[![managed with devset](https://img.shields.io/badge/managed_with-devset-0969da?style=flat-square&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHRpdGxlPmRldnNldDwvdGl0bGU+PHBhdGggZmlsbD0iI2YwZjZmYyIgZD0ibTE2IDMgMTMgNi41TDE2IDE2IDMgOS41WiIvPjxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2YwZjZmYyIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBzdHJva2Utd2lkdGg9IjIuNSIgZD0ibTMgMTYgMTMgNi41TDI5IDE2TTMgMjIuNSAxNiAyOWwxMy02LjUiLz48L3N2Zz4K)](https://github.com/atomix-labs/devset)

Write a Profile goes further: parts of a file, variables and features.
A New Rust Project and An Existing Repository apply a whole collection.
In CI makes drift fail a build.
examples/ holds each step as an example that runs.

Keyboard shortcuts

devset