Skip to content
zit Artifact [fa91eaee00]
Login

Artifact [fa91eaee00]

Artifact fa91eaee00546d96cb5e3e9b6137f89188d52419c64668831b2c733baccfbc86:


//! `zit settings` and `zit unset`: read and write settings at their tiers,
//! and the warnings a setting's versioned or ignored shadow earns.

const std = @import("std");
const ConfigPatch = zit.repo_config.ConfigPatch;
const Repository = @import("zit").Repository;
const cli = @import("zit").cli;
const configValue = zit.repo_config.configValue;
const diagnostics = @import("../cli/diagnostics.zig");
const help_pages = @import("../cli/help.zig");
const logstore = @import("zit").logstore;
const repoReadFail = diagnostics.repoReadFail;
const resolveCrlfGlob = zit.repo_config.resolveCrlfGlob;
const resolveSetting = zit.repo_config.resolveSetting;
const resolveSettingTiers = zit.repo_config.resolveSettingTiers;
const resolveSettingWith = zit.repo_config.resolveSettingWith;
const settings_help = help_pages.settings_help;
const stateOom = diagnostics.stateOom;
const storage = @import("zit").storage;
const storeAppendFail = diagnostics.storeAppendFail;
const storeOpenError = zit.repo_config.storeOpenError;
const updateConfig = zit.repo_config.updateConfig;
const zit = @import("zit");

// ---------------------------------------------------------------------------
// `zit remote [URL | --unset]` — read, set, or clear the single default peer URL
// (sync §4/§6). Bare prints the saved remote; a URL saves it; --unset clears it.
// A local, non-synced config value (`config.remote_url`) — anonymous only, no
// credential in the URL — that lets pull/push/sync omit their URL argument. Not
// a git-style named-remote registry: one value, matching the single-value config.
// ---------------------------------------------------------------------------

/// `zit settings [NAME [VALUE]]` — the local-settings surface, holding
/// exactly one setting today: `autosync`. Bare lists; NAME prints; NAME VALUE
/// sets. The value lives in the config frame like `remote_url` — local, never
/// synced — inverted in storage (the flag records OFF) so absence means the
/// fossil default, on.
pub fn runSettings(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    verb_args: []const []const u8,
    streams: cli.Streams,
    amb: cli.Ambient,
) cli.Exit {
    const parsed = switch (cli.parseSettingsArgs(verb_args)) {
        .ok => |p| p,
        .unknown_option => |tok| return cli.usageError(streams, "settings", .unknown_option, tok),
        .extra_argument => |tok| return cli.usageError(streams, "settings", .extra_argument, tok),
    };
    if (parsed.help) {
        streams.out.writeAll(settings_help) catch {};
        return .ok;
    }

    const root = (cli.resolveRoot(arena, io, amb.repo_override) catch return stateOom(streams, "settings")) orelse {
        diagnostics.reportNoRoot(streams, io, "settings", amb.repo_override);
        return .failure;
    };
    var root_dir = root.dir;
    defer root_dir.close(io);

    const zset = zit.settings;

    // The tier the operator named. `--global` selects WHERE a write lands and
    // which stored value a bare NAME reports; it never changes the fact that a
    // listing reports the value in EFFECT.
    const tier: Tier = if (parsed.global) .global else .repository;

    if (parsed.name) |name| {
        const setting = zset.Setting.byName(name) orelse {
            var names_buf: [256]u8 = undefined;
            streams.err.print(
                "zit settings: unknown setting '{s}' (known: {s})\n",
                .{ name, zset.knownNames(&names_buf) },
            ) catch {};
            return .failure;
        };
        if (parsed.value) |value| {
            return writeSetting(gpa, io, arena, root_dir, streams, amb, setting, value, tier);
        }
        return showSetting(gpa, io, arena, root_dir, streams, amb, setting, parsed.changed, parsed.value_only);
    }
    inline for (comptime std.enums.values(zset.Setting)) |setting| {
        const exit = showSetting(gpa, io, arena, root_dir, streams, amb, setting, parsed.changed, parsed.value_only);
        if (exit != .ok) return exit;
    }
    return .ok;
}

/// Write one setting into the tier the operator named.
///
/// Validation happens BEFORE either tier is touched, so a rejected value never
/// leaves a half-written global file or a config frame carrying a value the
/// reader will refuse.
fn writeSetting(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
    amb: cli.Ambient,
    setting: zit.settings.Setting,
    value: []const u8,
    tier: Tier,
) cli.Exit {
    const zset = zit.settings;
    switch (setting.kind()) {
        .boolean => if (zset.parseBool(value) == null and !(setting == .autosync and std.mem.eql(u8, value, "pullonly"))) {
            streams.err.print(
                "zit settings: {s} takes 'on' or 'off'{s}\ntry 'zit settings --help'\n",
                .{ setting.name(), if (setting == .autosync) " (or 'pullonly')" else "" },
            ) catch {};
            return .usage;
        },
        .string => if (tier == .repository and value.len > logstore.max_config_str) {
            // Refusing beats truncating: a truncated glob list silently stops
            // protecting files, and a truncated command silently runs a
            // different program.
            if (setting == .ignore_glob) {
                streams.err.print(
                    "zit settings: ignore-glob is limited to {d} bytes; use the versioned {s} file for longer lists\n",
                    .{ logstore.max_config_str, zit.ignore.versioned_path },
                ) catch {};
            } else {
                streams.err.print(
                    "zit settings: {s} is limited to {d} bytes\n",
                    .{ setting.name(), logstore.max_config_str },
                ) catch {};
            }
            return .failure;
        },
    }

    if (setting.tier() == .repository) {
        if (tier == .global) {
            streams.err.print("zit settings: {s} belongs to one repository and has no --global value\n", .{setting.name()}) catch {};
            return .usage;
        }
        if (!branchNameOk(value)) {
            streams.err.print("zit settings: '{s}' is not a branch name: it may not contain spaces or control characters\n", .{value}) catch {};
            return .usage;
        }
        if (value.len != 0) noteNoSuchBranch(gpa, io, root_dir, streams, value);
    }

    if (tier == .global) {
        writeGlobalSetting(gpa, io, arena, amb, setting, value) catch |e| switch (e) {
            error.OutOfMemory => return stateOom(streams, "settings"),
            error.NoGlobalHome => {
                streams.err.writeAll(
                    "zit settings: no global settings location (set $ZIT_CONFIG, $XDG_CONFIG_HOME or $HOME)\n",
                ) catch {};
                return .failure;
            },
            else => {
                streams.err.writeAll("zit settings: cannot write the global settings file\n") catch {};
                return .failure;
            },
        };
        streams.out.print("{s} {s}\n", .{ setting.name(), value }) catch {};
        // A global write that is shadowed locally changes nothing an operator
        // can see, which is precisely the confusion the provenance work exists
        // to end -- so say so at the moment it happens.
        const eff = resolveSetting(gpa, io, arena, root_dir, .{ .environ = amb.environ }, setting) catch return .ok;
        if (eff.source != .global) {
            streams.err.print(
                "note: the {s} tier still supplies {s} here, so this global value is not in effect\n",
                .{ eff.source.label(), setting.name() },
            ) catch {};
        }
        _ = noteVersionedShadow(io, root_dir, streams, setting, eff);
        if (setting == .ignore_glob) noteGitignorePresent(io, root_dir, streams);
        return .ok;
    }

    const patch = repositoryPatch(setting, value) orelse {
        streams.err.print(
            "zit settings: {s} cannot be stored in this repository yet\n",
            .{setting.name()},
        ) catch {};
        return .failure;
    };
    updateConfig(gpa, io, root_dir, patch) catch |e| switch (e) {
        error.OutOfMemory => return stateOom(streams, "settings"),
        else => return storeAppendFail(streams, "settings", e),
    };
    streams.out.print("{s} {s}\n", .{ setting.name(), value }) catch {};
    // The value just written IS the repository tier, so the shadow question is
    // answerable without re-opening the store.
    const r = resolveSettingWith(io, arena, root_dir, .{ .environ = amb.environ }, setting, value) catch
        return .ok;
    _ = noteVersionedShadow(io, root_dir, streams, setting, r);
    if (setting == .ignore_glob) noteGitignorePresent(io, root_dir, streams);
    return .ok;
}

/// A name a branch tag can carry: one token, so no whitespace or control
/// characters. Empty is allowed and resets the setting to its default.
fn branchNameOk(name: []const u8) bool {
    for (name) |c| if (c <= ' ' or c == 0x7f) return false;
    return true;
}

/// Setting the main branch to a name no open branch has is allowed, as in
/// Fossil: the branch may be about to arrive. Said on stderr, because a typo
/// here points `update`, `merge` and the forge at nothing.
fn noteNoSuchBranch(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, streams: cli.Streams, name: []const u8) void {
    var repo: Repository = undefined;
    repo.open(gpa, io, root_dir, .{ .mode = .full }) catch return;
    defer repo.deinit(gpa);
    const leaves = repo.state().openLeavesOf(gpa, name) catch return;
    defer gpa.free(leaves);
    if (leaves.len == 0) streams.err.print("note: no open branch is named '{s}' yet\n", .{name}) catch {};
}

/// The config-frame patch for a repository-tier write, or null for a setting
/// the frame does not yet carry.
fn repositoryPatch(setting: zit.settings.Setting, value: []const u8) ?ConfigPatch {
    const on = zit.settings.parseBool(value);
    return switch (setting) {
        // Both booleans record the explicit-set bit alongside the value, which
        // is what makes "explicitly the default" distinguishable from untouched.
        .autosync => if (std.mem.eql(u8, value, "pullonly"))
            .{ .autosync_off = false, .autosync_set = true, .autosync_mode = "pullonly" }
        else
            .{ .autosync_off = !(on orelse return null), .autosync_set = true, .autosync_mode = "" },
        .editor => .{ .editor = value },
        .clearsign => .{ .clearsign = on orelse return null, .clearsign_set = true },
        .repo_cksum => .{ .repo_cksum_off = !(on orelse return null), .repo_cksum_set = true },
        .ignore_glob => .{ .ignore_glob = value },
        .pgp_command => .{ .pgp_command = value },
        .keep_glob => .{ .keep_glob = value },
        .manifest => .{ .manifest = value },
        .before_commit => .{ .before_commit = value },
        .binary_glob => .{ .binary_glob = value },
        .crlf_glob => .{ .crlf_glob = value },
        .crnl_glob => .{ .crnl_glob = value },
        .clean_glob => .{ .clean_glob = value },
        .empty_dirs => .{ .empty_dirs = value },
        .encoding_glob => .{ .encoding_glob = value },
        // Boolean-valued, stored as the operator's own text: `settings
        // dotfiles yes` round-trips as `yes`, and `settings.isTruth` is the
        // one thing that reads it.
        .dotfiles => .{ .dotfiles = value },
        .mimetypes => .{ .mimetypes = value },
        .attachment_size_limit => .{ .attachment_size_limit = value },
        .main_branch => .{ .default_branch = value },
    };
}

/// Read-modify-write the operator-scope settings file, creating its directory
/// when absent. Read-modify-write rather than append so a second edit of the
/// same setting replaces the first instead of leaving a dead line above it.
fn writeGlobalSetting(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    amb: cli.Ambient,
    setting: zit.settings.Setting,
    value: []const u8,
) !void {
    const zset = zit.settings;
    var path_buf: [1024]u8 = undefined;
    const g = zset.globalPath(amb.environ, &path_buf) orelse return error.NoGlobalHome;
    const cwd = std.Io.Dir.cwd();
    const existing = cwd.readFileAlloc(io, g.path, arena, .limited(zset.max_versioned_bytes)) catch "";
    const next = try zset.globalSet(gpa, existing, setting, value);
    defer gpa.free(next);
    if (g.dir.len != 0) cwd.createDirPath(io, g.dir) catch {};
    var f = cwd.createFile(io, g.path, .{ .truncate = true }) catch return error.Storage;
    defer f.close(io);
    f.writePositionalAll(io, next, 0) catch return error.Storage;
}

/// Which stored tier a `zit settings` invocation addresses.
const Tier = enum { repository, global };

/// Print one setting as `NAME VALUE` plus the tier that supplied it.
///
/// The provenance column is the point. zit has four places a value can
/// live, and a display that showed only the value would let an operator edit
/// the shadowed tier -- twice -- while the effective answer never moved. The
/// note is on stderr so `zit settings NAME` remains a clean value on stdout for
/// a script.
fn showSetting(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
    amb: cli.Ambient,
    setting: zit.settings.Setting,
    only_changed: bool,
    value_only: bool,
) cli.Exit {
    const r = resolveSetting(gpa, io, arena, root_dir, .{ .environ = amb.environ }, setting) catch |e| switch (e) {
        error.OutOfMemory => return stateOom(streams, "settings"),
        else => return repoReadFail(streams, "settings"),
    };
    if (only_changed and r.source == .default) return .ok; // --changed
    if (value_only) {
        streams.out.print("{s}\n", .{r.value}) catch {}; // --value
    } else {
        streams.out.print("{s} {s}\n", .{ setting.name(), r.value }) catch {};
    }
    // Only say where it came from when that is not the obvious answer: naming
    // the tier for every default would bury the two lines that matter. One
    // fact, one line: when a versioned file is shadowing a stored value the
    // note SAYS so and replaces the provenance line, and when `.no-warn`
    // silences that, the provenance line still names the file that is live.
    if (!setting.versionable()) noteVersionedIgnored(io, root_dir, streams, setting);
    if (noteVersionedShadow(io, root_dir, streams, setting, r)) return .ok;
    if (r.source == .versioned) {
        const dir = r.versioned_dir orelse .zit;
        streams.err.print(
            "note: {s} is set in {s}/{s}\n",
            .{ setting.name(), dir.dirName(), setting.name() },
        ) catch {};
    } else if (r.source != .default and r.source != .repository) {
        streams.err.print(
            "note: {s} is set in the {s} tier\n",
            .{ setting.name(), r.source.label() },
        ) catch {};
    }
    return .ok;
}

/// `resolveSettingWith` with the versioned tier read from
/// the check-in `rid` instead of the working tree: what `open` needs, since
/// its tree does not exist yet. Same two file names in the same order, the
/// same comment stripping, the same tiers below; fossil's `db_get_versioned`
/// reads the file out of the check-in through `historical_blob` too.
pub fn checkinSetting(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    repo: *Repository,
    rid: Repository.Rid,
    amb: cli.Ambient,
    config: ?*const logstore.Config,
    setting: zit.settings.Setting,
) !zit.settings.Resolved {
    const zset = zit.settings;
    var c: zset.Candidates = .{};
    if (setting.versionable()) {
        var fossil_buf: [128]u8 = undefined;
        var zit_buf: [128]u8 = undefined;
        const candidates = .{ setting.fossilVersionedPath(&fossil_buf), setting.versionedPath(&zit_buf) };
        const dirs = [_]zset.VersionedDir{ .fossil, .zit };
        inline for (candidates, 0..) |maybe_path, i| {
            if (c.versioned == null) {
                if (maybe_path) |path| {
                    if (checkinFileText(gpa, arena, repo, rid, path)) |text| {
                        c.versioned = zset.stripCommentLines(text);
                        c.versioned_dir = dirs[i];
                    }
                }
            }
        }
    }
    const repository = if (config) |cf| try configValue(arena, cf, setting) else null;
    return resolveSettingTiers(io, arena, .{ .environ = amb.environ }, setting, &c, repository);
}

/// The content of `path` in check-in `rid`, copied into `arena` and bounded
/// like a versioned file on disk; null when the check-in has no such file or
/// it cannot be read (the tiers below then answer, as for an unreadable file).
fn checkinFileText(gpa: std.mem.Allocator, arena: std.mem.Allocator, repo: *Repository, rid: Repository.Rid, path: []const u8) ?[]u8 {
    const card = (repo.fileAt(gpa, rid, path) catch return null) orelse return null;
    defer Repository.freeFileCard(gpa, card);
    const hash = card.hash orelse return null;
    const bytes = (repo.blob(gpa, hash) catch return null) orelse return null;
    defer gpa.free(bytes);
    if (bytes.len > zit.settings.max_versioned_bytes) return null;
    return arena.dupe(u8, bytes) catch null;
}

/// The local settings `zit settings` edits, as one table rather than an
/// if-chain per name. Every one of them is repo-LOCAL and never crosses the
/// wire: `autosync` and `ignore-glob` because they describe this working
/// copy's habits, `clearsign` and `pgp-command` because fossil classifies the
/// latter SENSITIVE and puts the former in no config group. The settings
/// that DO propagate are a separate mechanism — versioned `.zit-settings/`
/// files and the sync §9.3 config groups — not this verb.
const LocalSetting = enum {
    autosync,
    ignore_glob,
    clearsign,
    pgp_command,

    const known_names = "autosync, ignore-glob, clearsign, pgp-command";

    const Kind = enum { boolean, string };

    fn wireName(self: LocalSetting) []const u8 {
        return switch (self) {
            .autosync => "autosync",
            .ignore_glob => "ignore-glob",
            .clearsign => "clearsign",
            .pgp_command => "pgp-command",
        };
    }

    fn byName(name: []const u8) ?LocalSetting {
        inline for (comptime std.enums.values(LocalSetting)) |s| {
            if (std.mem.eql(u8, name, s.wireName())) return s;
        }
        return null;
    }

    fn kind(self: LocalSetting) Kind {
        return switch (self) {
            .autosync, .clearsign => .boolean,
            .ignore_glob, .pgp_command => .string,
        };
    }

    /// This setting's stored value as display text, borrowed from `current`.
    fn read(self: LocalSetting, current: Settings) []const u8 {
        return switch (self) {
            // autosync is stored as the DEVIATION, so the flag reads inverted.
            .autosync => if (current.autosync_off) "off" else "on",
            .clearsign => if (current.clearsign) "on" else "off",
            .ignore_glob => current.ignore_glob,
            .pgp_command => current.pgp_command,
        };
    }

    /// The patch that sets this setting to `value`, or null when `value` is
    /// not one this setting accepts.
    fn patch(self: LocalSetting, value: []const u8) ?ConfigPatch {
        switch (self) {
            .autosync, .clearsign => {
                const on = if (std.mem.eql(u8, value, "on"))
                    true
                else if (std.mem.eql(u8, value, "off"))
                    false
                else
                    return null;
                // Inverted in storage for autosync (absent = fossil's default,
                // on); plain for clearsign (absent = fossil's default, off).
                return switch (self) {
                    .autosync => .{ .autosync_off = !on },
                    .clearsign => .{ .clearsign = on },
                    else => unreachable,
                };
            },
            .ignore_glob, .pgp_command => {
                // The config frame caps every string field; refusing beats
                // truncating, which would silently change what runs or what
                // is ignored.
                if (value.len > logstore.max_config_str) return null;
                return switch (self) {
                    .ignore_glob => .{ .ignore_glob = value },
                    .pgp_command => .{ .pgp_command = value },
                    else => unreachable,
                };
            },
        }
    }

    fn reportBadValue(self: LocalSetting, streams: cli.Streams, value: []const u8) void {
        switch (self.kind()) {
            .boolean => streams.err.print(
                "zit settings: {s} takes 'on' or 'off'\ntry 'zit settings --help'\n",
                .{self.wireName()},
            ) catch {},
            .string => {
                _ = value;
                if (self == .ignore_glob) {
                    streams.err.print(
                        "zit settings: ignore-glob is limited to {d} bytes; use the versioned {s} file for longer lists\n",
                        .{ logstore.max_config_str, zit.ignore.versioned_path },
                    ) catch {};
                } else {
                    streams.err.print(
                        "zit settings: {s} is limited to {d} bytes\n",
                        .{ self.wireName(), logstore.max_config_str },
                    ) catch {};
                }
            },
        }
    }

    fn print(self: LocalSetting, streams: cli.Streams, value: []const u8) void {
        streams.out.print("{s} {s}\n", .{ self.wireName(), value }) catch {};
    }
};

/// Every local setting's value, read in ONE store open. Four separate readers
/// would open, scan and close the log four times for a bare `zit settings`.
const Settings = struct {
    autosync_off: bool = false,
    clearsign: bool = false,
    ignore_glob: []const u8 = "",
    pgp_command: []const u8 = "",
};

/// Backing store for the two string settings a `Settings` borrows: the config
/// frame's own buffer dies with the read, so the values are copied out.
const SettingsBuf = [2 * logstore.max_config_str]u8;

fn readSettings(
    gpa: std.mem.Allocator,
    io: std.Io,
    dir: std.Io.Dir,
    buf: *SettingsBuf,
) !Settings {
    var file = cli.openStoreRead(io, dir) catch |e| return storeOpenError(e);
    defer file.close(io);
    const st = file.stat(io) catch return error.Storage;
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = logstore.LogStore.openReadOnly(gpa, fs.storageFile()) catch |e| switch (e) {
        error.OutOfMemory => return error.OutOfMemory,
        else => return error.Storage,
    };
    defer log.deinit(gpa);
    var oc = (log.readConfig(gpa) catch |e| switch (e) {
        error.OutOfMemory => return error.OutOfMemory,
        else => return error.Storage,
    }) orelse return .{};
    defer oc.deinit(gpa);
    const glob = oc.config.ignore_glob;
    const pgp = oc.config.pgp_command;
    std.debug.assert(glob.len + pgp.len <= buf.len);
    @memcpy(buf[0..glob.len], glob);
    @memcpy(buf[glob.len..][0..pgp.len], pgp);
    return .{
        .autosync_off = oc.config.autosync_off,
        .clearsign = oc.config.clearsign,
        .ignore_glob = buf[0..glob.len],
        .pgp_command = buf[glob.len..][0..pgp.len],
    };
}

/// fossil's posture: when the working tree carries the versioned
/// ignore file, the sweeps use IT, and a display of the local setting must
/// say so — a value that reads as live while being shadowed is how an
/// operator edits the wrong one twice.
fn noteVersionedShadow(
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
    setting: zit.settings.Setting,
    r: zit.settings.Resolved,
) bool {
    const shadowed = r.shadowed orelse return false;
    const dir = r.versioned_dir orelse return false;
    if (noWarnPresent(io, root_dir, setting)) return false;
    streams.err.print(
        "note: {s}/{s} overrides the {s} setting in the {s} tier; create {s}/{s}.no-warn to silence\n",
        .{ dir.dirName(), setting.name(), setting.name(), shadowed.label(), dir.dirName(), setting.name() },
    ) catch {};
    return true;
}

/// Whether either settings directory holds `<name>.no-warn`.
///
/// EITHER silences the note, whichever directory holds the winning file:
/// fossil has one directory and cannot pin this, and zit picks the permissive
/// rule because the two directories are one setting with two spellings -- a
/// silence the operator asked for should not evaporate because a later commit
/// chose the other spelling.
fn noWarnPresent(io: std.Io, root_dir: std.Io.Dir, setting: zit.settings.Setting) bool {
    inline for (comptime std.enums.values(zit.settings.VersionedDir)) |d| {
        var buf: [160]u8 = undefined;
        if (std.fmt.bufPrint(&buf, "{s}/{s}.no-warn", .{ d.dirName(), setting.name() })) |path| {
            if (root_dir.statFile(io, path, .{ .follow_symlinks = false })) |_| return true else |_| {}
        } else |_| {}
    }
    return false;
}

/// One line for a versioned file that cannot supply its
/// setting. `autosync` describes this machine's relationship to the network,
/// so no tracked file may set it; fossil ignores such a file silently, and zit
/// says so once rather than leaving the operator to wonder why their committed
/// value does nothing.
pub fn noteVersionedIgnored(
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
    setting: zit.settings.Setting,
) void {
    std.debug.assert(!setting.versionable());
    inline for (comptime std.enums.values(zit.settings.VersionedDir)) |d| {
        var buf: [160]u8 = undefined;
        if (std.fmt.bufPrint(&buf, "{s}/{s}", .{ d.dirName(), setting.name() })) |path| {
            if (root_dir.statFile(io, path, .{ .follow_symlinks = false })) |_| {
                // Two reasons a file cannot supply a setting, and the note says
                // which: network posture belongs to the machine, and an
                // executable-tier value a clone could set would be remote code
                // execution.
                const why: []const u8 = switch (setting.tier()) {
                    .local => "a local setting",
                    .executable => "never supplied by a tracked file",
                    .repository => "kept in the repository's own config",
                    .data, .consented => unreachable, // versionable; not this path
                };
                streams.err.print(
                    "note: {s} is versioned and ignored; {s} is {s}\n",
                    .{ path, setting.name(), why },
                ) catch {};
            } else |_| {}
        } else |_| {}
    }
}

/// `.zitignore` is not a settings file -- it is a second DIALECT that applies
/// alongside whatever `ignore-glob` resolves to, so its presence is
/// worth one line but is not a shadowing.
fn noteGitignorePresent(io: std.Io, root_dir: std.Io.Dir, streams: cli.Streams) void {
    if (root_dir.statFile(io, zit.ignore.gitignore_path, .{ .follow_symlinks = false })) |_| {
        streams.err.print(
            "note: {s} is present; its patterns apply in addition to the ignore-glob setting\n",
            .{zit.ignore.gitignore_path},
        ) catch {};
    } else |_| {}
}

test "resolveCrlfGlob falls back to crnl-glob from one frame" {
    // The commit gate holds the store's write lock and reads its config once,
    // so both spellings are answered from that frame -- no second store open,
    // and no way for the two reads to see different bytes.
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    const amb: cli.Ambient = .{ .now_epoch = 0, .user_env = null };

    // The older spelling answers while the newer one is absent.
    const older: logstore.Config = .{
        .hash_policy = 0,
        .default_branch = "trunk",
        .project_id = "p",
        .crnl_glob = "*.txt",
    };
    const from_crnl = try resolveCrlfGlob(io, arena, tmp.dir, .{ .environ = amb.environ }, &older);
    try std.testing.expectEqualStrings("*.txt", from_crnl.value);
    try std.testing.expectEqual(zit.settings.Source.repository, from_crnl.source);

    // `crlf-glob` present REPLACES it, exactly as fossil's
    // `db_get("crlf-glob", db_get("crnl-glob",""))` does.
    const newer: logstore.Config = .{
        .hash_policy = 0,
        .default_branch = "trunk",
        .project_id = "p",
        .crlf_glob = "*.c",
        .crnl_glob = "*.txt",
    };
    const from_crlf = try resolveCrlfGlob(io, arena, tmp.dir, .{ .environ = amb.environ }, &newer);
    try std.testing.expectEqualStrings("*.c", from_crlf.value);

    // No frame and no versioned file: nothing is declared, so the class is
    // not checked at all.
    const none = try resolveCrlfGlob(io, arena, tmp.dir, .{ .environ = amb.environ }, null);
    try std.testing.expectEqual(zit.settings.Source.default, none.source);
    try std.testing.expectEqualStrings("", none.value);
}