oxy describe names builds; tags name changes; commit -F 6a81dbab471d

/// What `oxy describe` reports about the working copy (spec §10.1).

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Description {

    /// The tag of the base state, or the nearest tag below it.

    pub tag: Option<String>,

    /// Changes in the base state that the tag's state lacks (0: exact).

    pub distance: usize,

    pub bookmark: String,

    /// The base's newest head.

    pub change: ChangeId,

    pub hash: ChangeHash,

    /// Whether the working copy has uncommitted changes.

    pub dirty: bool,

}

impl Description {

    /// `v1.2`, `v1.2-3-8c5ea12a`, or `develop-8c5ea12a`, and `-dirty`.

    pub fn line(&self) -> String {

        let short = self.change.short(8);

        let base = match (&self.tag, self.distance) {

            (Some(t), 0) => t.clone(),

            (Some(t), n) => format!("{t}-{n}-{short}"),

            (None, _) => format!("{}-{short}", self.bookmark),

        };

        if self.dirty {

            format!("{base}-dirty")

        } else {

            base

        }

    }

}

impl Repo {

    /// Name the working copy for builds (`oxy describe`, like `git

    /// describe`): the tag of its base state; else the nearest tag whose

    /// state the base contains, with how many changes it adds and its

    /// newest head; else the bookmark and that head. `dirty` when the

    /// working copy has uncommitted changes.

    pub fn describe_working_copy(&self) -> Result<Description> {

        let snap = self.snapshot_status("oxy describe")?;

        let dirty = !snap.statuses.is_empty();

        let base = snap.base.maximal(&snap.wc.deps);

        let Some(&newest) = base

            .iter()

            .max_by_key(|h| snap.base.get(h).map(|c| (c.hlc, **h)))

        else {

            return fail("the working copy sits on no change yet");

        };

        let Some(change) = snap.base.get(&newest).map(|m| m.change_id) else {

            return fail("the working copy's base is not loaded");

        };

        let mut sorted = base.clone();

        sorted.sort();

        let mut best: Option<(usize, String)> = None;

        for t in self.tags()? {

            if !t.heads.iter().all(|h| snap.base.contains(h)) {

                continue;

            }

            let mut tagged: std::collections::HashSet<ChangeHash> =

                t.heads.iter().copied().collect();

            for h in &t.heads {

                tagged.extend(snap.base.closure(h).iter().copied());

            }

            let mut heads = t.heads.clone();

            heads.sort();

            let distance = if heads == sorted {

                0

            } else {

                snap.base.len().saturating_sub(tagged.len()).max(1)

            };

            if best

                .as_ref()

                .is_none_or(|(d, n)| distance < *d || (distance == *d && t.name < *n))

            {

                best = Some((distance, t.name));

            }

        }

        let (distance, tag) = match best {

            Some((d, t)) => (d, Some(t)),

            None => (0, None),

        };

        Ok(Description {

            tag,

            distance,

            bookmark: self.config.bookmark.clone(),

            change,

            hash: newest,

            dirty,

        })

    }

}

pub use inspect::{BisectStep, BlameLine, Description};

    /// Resolve a change by ChangeId prefix, `#hash` prefix, `@` (working

    /// copy), bookmark or tag (the one head of its state).

        let named = match self.view()?.bookmarks.get(spec) {

            Some(st) => Some(("bookmark", self.store.get_state(st)?.heads)),

            None => self.tag_heads(spec)?.map(|h| ("tag", h)),

        };

        if let Some((kind, heads)) = named {

                n => fail(format!("{kind} {spec} has {n} heads; name a change, or use it where a state is expected")),

- [x] M9a `oxy describe` naming (tag, else nearest tag + distance + change, else bookmark + change, `-dirty`, `--json`), tags accepted where a change is and `tag list` showing heads (feedback 4); `commit -F` (6).

- [ ] M9b `submodule status` shows added-but-unpinned and has `--json` (5, 7); doctor before the first commit (8).

A repository holds any number of bookmarks. Each workspace has a **current bookmark** (`oxy bookmark switch NAME`, recorded per workspace) that its working copy sits on and that `commit`, `log`, `push`, and `pull` act on by default. Switching refuses uncommitted work unless told what to do with it: `--discard` drops it, and `--carry` takes it along when every path it touches is the same in NAME's state as in the working copy's base (so the same edits apply there), refusing and naming the paths otherwise. `oxy bookmark create feat && oxy bookmark switch feat --carry` moves work started on one bookmark onto a new one. `oxy bookmark create NAME [CHANGE..]` names a new state (default: the current working copy's base heads), `set NAME CHANGE..` moves one, `delete NAME` removes it (its changes stay until unreachable, §21), `list` shows all with their heads and the remote-tracking difference, and `oxy merge NAME` unions the named bookmark's heads into the current one, which is the whole of merging in this model: no merge change, conflicts reified (§9); a working copy without changes follows the merge, whichever state it sat on. `oxy checkout NAME` materializes a bookmark without switching to it; with uncommitted work it refuses, naming each changed path and how it changed (a *removed* path is in the working copy's base but not on disk), unless `--discard` or `--carry` (as for switching) says what to do with the work. Bookmark names, then tag names, are resolved before change prefixes wherever a change is expected (a bookmark or tag names a change when its state has one head). For builds, `oxy describe` without `-m` names the working copy as `git describe` does: its base state's tag (`v1.2`), else the nearest tag whose state the base contains with the number of changes it adds and the newest head's ChangeId (`v1.2-3-8c5ea12a`), else the bookmark and that ChangeId (`develop-8c5ea12a`), with `-dirty` when the working copy has uncommitted changes; `--json` gives the parts.

- `oxy commit` (`-m MSG`, or `-F FILE` with `-` for standard input) sets the message, sets `kind = normal`, and starts a fresh working-copy change on top of it. The change is signed immediately if `core.sign = "change"`; with the default `core.sign = "seal"` it is left unsigned locally and covered by a seal at push time (§14.4).

oxy describe [CHANGE] [-m MSG]      oxy amend [-m MSG] [--into CHANGE]

        #[arg(short, long, required_unless_present = "file", conflicts_with = "file")]

        message: Option<String>,

        /// Read the message from FILE (`-` for standard input)

        #[arg(short = 'F', long, value_name = "FILE")]

        file: Option<PathBuf>,

    /// With -m, change the message of a head; without, name the working

    /// copy for a build: its tag, or the nearest tag plus distance and

    /// change, or the bookmark and change, and -dirty

        message: Option<String>,

        /// Machine-readable output (naming only)

        #[arg(long, conflicts_with = "message")]

        json: bool,

            file,

        } => {

            let message = match (message, file) {

                (Some(m), _) => m,

                (None, Some(f)) if f.as_os_str() == "-" => {

                    let mut s = String::new();

                    std::io::Read::read_to_string(&mut std::io::stdin(), &mut s)?;

                    s

                }

                (None, Some(f)) => std::fs::read_to_string(&f).map_err(|e| {

                    anyhow::anyhow!("reading the message from {}: {e}", f.display())

                })?,

                (None, None) => anyhow::bail!("a commit message is required (-m or -F)"),

            };

            workspace::commit(&message, &depends_on, &paths, interactive, &hunks)

        }

        Cmd::Describe {

            message,

            change,

            json,

        } => match message {

            Some(m) => workspace::describe(&m, change.as_deref()),

            None if change.is_some() => {

                anyhow::bail!(

                    "naming works on the working copy; to change a head's message pass -m"

                )

            }

            None => workspace::describe_name(json),

        },

/// `oxy describe` without -m: the working copy's name for a build.

pub fn describe_name(as_json: bool) -> Result<i32> {

    let repo = open()?;

    let d = repo.describe_working_copy()?;

    if as_json {

        println!(

            "{}",

            json::obj([

                ("describe", json::s(&d.line())),

                ("tag", json::opt(d.tag.as_ref(), |t| json::s(t))),

                ("distance", json::n(d.distance)),

                ("bookmark", json::s(&d.bookmark)),

                ("change", json::s(&d.change.to_hex())),

                ("hash", json::s(&d.hash.to_hex())),

                ("dirty", json::b(d.dirty)),

            ])

        );

    } else {

        println!("{}", d.line());

    }

    Ok(0)

}

            // The heads, as `oxy log` shows changes, not the state hash.

            ui::hash(

                t.heads

                    .iter()

                    .map(|h| format!("#{}", h.short(12)))

                    .collect::<Vec<_>>()

                    .join(" ")

            ),

/// `oxy commit -F`, `oxy describe` naming and tags as changes (feedback

/// 4 and 6).

#[test]

fn commit_from_a_file_and_describe_for_builds() {

    let tmp = tempfile::tempdir().unwrap();

    let home = tmp.path().join("home");

    std::fs::create_dir_all(&home).unwrap();

    let dir = tmp.path().join("r");

    std::fs::create_dir_all(&dir).unwrap();

    assert_eq!(oxy(&dir, &home, &["init"]).0, 0);

    write(&dir, "a.txt", "a\n");

    write(

        tmp.path(),

        "msg.txt",

        "Subject from a file\n\nA body\nof two lines.\n",

    );

    let msg = tmp.path().join("msg.txt");

    let (code, _, err) = oxy(&dir, &home, &["commit", "-F", msg.to_str().unwrap()]);

    assert_eq!(code, 0, "{err}");

    let log = json(&dir, &home, &["log", "--json", "-n", "2"]);

    assert_eq!(

        log["changes"][1]["message"],

        "Subject from a file\n\nA body\nof two lines."

    );

    assert_ne!(oxy(&dir, &home, &["commit"]).0, 0, "a message is required");

    // Untagged: bookmark and change; a tag names it; later work counts.

    let d = json(&dir, &home, &["describe", "--json"]);

    assert_eq!(

        (d["tag"].clone(), d["dirty"].clone()),

        (Value::Null, Value::Bool(false))

    );

    let change = d["change"].as_str().unwrap().to_string();

    assert_eq!(d["describe"], format!("main-{}", &change[..8]));

    assert_eq!(

        oxy(&dir, &home, &["tag", "create", "v0.1.0", "-m", "first"]).0,

        0

    );

    let (_, out, _) = oxy(&dir, &home, &["describe"]);

    assert_eq!(String::from_utf8_lossy(&out).trim(), "v0.1.0");

    let (code, out, err) = oxy(&dir, &home, &["show", "v0.1.0"]);

    assert_eq!(code, 0, "a tag names its change: {err}");

    assert!(String::from_utf8_lossy(&out).contains("Subject from a file"));

    write(&dir, "b.txt", "b\n");

    let d = json(&dir, &home, &["describe", "--json"]);

    assert_eq!(d["describe"], "v0.1.0-dirty");

    assert_eq!(oxy(&dir, &home, &["commit", "-m", "b"]).0, 0);

    write(&dir, "c.txt", "c\n");

    assert_eq!(oxy(&dir, &home, &["commit", "-m", "c"]).0, 0);

    let d = json(&dir, &home, &["describe", "--json"]);

    let change = d["change"].as_str().unwrap();

    assert_eq!(d["distance"], 2);

    assert_eq!(d["describe"], format!("v0.1.0-2-{}", &change[..8]));

}