# Repository Guidelines

## Project Structure & Modules

- `crates/`: Rust workspace members (CLI, node, helpers). Treat each crate as an isolated package.

- `build.rs`, `build/`: build-time artifacts and helpers.

- `scripts/`: maintenance utilities (e.g., `scripts/build-man-pages.sh`).

- `systemd/`, `debian/`: packaging/service files.

- `README.md`, `ARCHITECTURE.md`, `*.adoc`: docs and man pages.

## Build, Test, and Dev

- Build: `cargo build --workspace --all-features`

- Check: `cargo check --workspace`

- Test (std): `cargo test --workspace`

- Test (faster): `cargo nextest run --workspace` (if installed)

- Lint: `cargo clippy --workspace --all-targets -- -D warnings`

- Format: `cargo fmt --all -- --check`

- Security: `cargo deny check` and `cargo audit`

- Nix dev shell: `nix develop` then run the above. CI parity: `nix flake check`.

## Coding Style & Naming

- Rust 1.88 (see `rust-toolchain.toml`). Run `cargo fmt` before pushing.

- Prefer module paths over `#[path]` includes; crate-local `mod` layout under `src/`.

- Naming: modules `snake_case`, types/traits `PascalCase`, functions/vars `snake_case`.

- Deny warnings in CI; fix all Clippy findings before submitting.

## Testing Guidelines

- Use Rust’s built-in test framework; place unit tests in `src/*` with `#[cfg(test)]` and integration tests under `crates/<name>/tests/>`.

- Keep tests deterministic; avoid network and time flakiness.

- Run: `cargo nextest run --workspace` (or `cargo test`). Aim for meaningful coverage across public APIs.

## Commit & PR Guidelines

- Commit messages: imperative mood with a scoped prefix when helpful (e.g., `cli/patch: ...`, `term/table: ...`). Keep subject ≤72 chars; add a concise body when needed.

- PRs must include: clear description, rationale, and testing notes. Link related issues. Update docs/man pages when flags or behavior change.

- Pre-submit checklist: `cargo fmt`, `cargo clippy -D warnings`, tests green, `cargo deny check`.

## Agent-Specific Notes

- Make minimal, focused changes; follow existing patterns in the touched crate.

- Do not refactor unrelated code. Keep file moves atomic and justified.

- If unsure about behavior, search usage via `rg '<symbol>'` and update call sites.

use std::env;

use std::process::Command;

fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Set a build-time `GIT_HEAD` env var which includes the commit id;

    // such that we can tell which code is running.

    let hash = env::var("GIT_HEAD").unwrap_or_else(|_| {

        Command::new("git")

            .arg("rev-parse")

            .arg("--short")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or("unknown".into())

    });

    let version = if let Ok(version) = env::var("RADICLE_VERSION") {

        version

    } else {

        "pre-release".to_owned()

    };

    // Set a build-time `SOURCE_DATE_EPOCH` env var which includes the commit time.

    let commit_time = env::var("SOURCE_DATE_EPOCH").unwrap_or_else(|_| {

        Command::new("git")

            .arg("log")

            .arg("-1")

            .arg("--pretty=%ct")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or(0.to_string())

    });

    println!("cargo::rustc-env=RADICLE_VERSION={version}");

    println!("cargo::rustc-env=SOURCE_DATE_EPOCH={commit_time}");

    println!("cargo::rustc-env=GIT_HEAD={hash}");

    Ok(())

}

$ sh -c "printf '%s\\n' 'Alan K' >> CONTRIBUTORS"

$ sh -c "printf '%s\\n' 'Jason Bourne' >> CONTRIBUTORS"

$ sh -c "printf '%s\\n' 'Mel Farna' >> CONTRIBUTORS"

    term::print_with_pager(table)?;

        term::print_with_pager(table)?;

                term::print_with_pager(table)?;

        term::print_with_pager(table)?;

    term::print_with_pager(table)?;

    fn item_diff(&mut self, item: ReviewItem) -> Result<git::raw::Diff<'_>, Error> {

                list::print_tracked(tracked.iter())?;

                list::print_untracked(untracked.iter())?;

                list::print_tracked(tracked.iter())?;

                list::print_untracked(untracked.iter())?;

use radicle_term::Table;

pub fn print_tracked<'a>(tracked: impl Iterator<Item = &'a Tracked>) -> anyhow::Result<()> {

    let table = Table::from_iter(tracked.into_iter().flat_map(|Tracked { direction, name }| {

    }));

    term::print_with_pager(table)?;

    Ok(())

pub fn print_untracked<'a>(untracked: impl Iterator<Item = &'a Untracked>) -> anyhow::Result<()> {

    let table = Table::from_iter(untracked.into_iter().map(|Untracked { remote, alias }| {

    }));

    term::print_with_pager(table)?;

    Ok(())

use radicle::node::Node;

use radicle::profile::Profile;

    term::print_with_pager(table)?;

    term::print_with_pager(table)?;

pub fn rad_remotes(repo: &git2::Repository) -> anyhow::Result<Vec<Remote<'_>>> {

pub fn rad_remote(repo: &Repository) -> anyhow::Result<(git2::Remote<'_>, RepoId)> {

    ) -> anyhow::Result<(git::Remote<'_>, Option<BranchName>)> {

/// Print an element with automatic paging when there are too many lines.

/// This function automatically detects if the content is too long for the terminal

/// and uses a pager if necessary.

pub fn print_with_pager(elem: impl Element) -> anyhow::Result<()> {

    elem.print_with_pager()?;

    Ok(())

}

    let table: term::Table<2, _> = commits

        .collect();

    term::print_with_pager(table)?;

pub fn try_branch(reference: git::raw::Reference<'_>) -> anyhow::Result<git::raw::Branch<'_>> {

    // Explicit cleanup order to prevent panic during teardown

    // Shutdown nodes in reverse order of creation

    drop(eve);

    drop(bob);

    drop(alice);

        .env("COLUMNS", "120")

        .env("LINES", "30")

    pub fn to_component(&self) -> radicle_git_ext::ref_format::Component<'_> {

#[allow(dead_code)]

use std::env;

use std::process::Command;

fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Set a build-time `GIT_HEAD` env var which includes the commit id;

    // such that we can tell which code is running.

    let hash = env::var("GIT_HEAD").unwrap_or_else(|_| {

        Command::new("git")

            .arg("rev-parse")

            .arg("--short")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or("unknown".into())

    });

    let version = if let Ok(version) = env::var("RADICLE_VERSION") {

        version

    } else {

        "pre-release".to_owned()

    };

    // Set a build-time `SOURCE_DATE_EPOCH` env var which includes the commit time.

    let commit_time = env::var("SOURCE_DATE_EPOCH").unwrap_or_else(|_| {

        Command::new("git")

            .arg("log")

            .arg("-1")

            .arg("--pretty=%ct")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or(0.to_string())

    });

    println!("cargo::rustc-env=RADICLE_VERSION={version}");

    println!("cargo::rustc-env=SOURCE_DATE_EPOCH={commit_time}");

    println!("cargo::rustc-env=GIT_HEAD={hash}");

    Ok(())

}

        // Shutdown the handle with error handling to prevent panic during cleanup

        if let Err(e) = unsafe { ManuallyDrop::take(&mut self.handle) }.shutdown() {

            log::warn!(target: "test", "Failed to shutdown node {}: {}", self.id, e);

        }

        // Join the thread with error handling to prevent panic during cleanup

        match unsafe { ManuallyDrop::take(&mut self.thread) }.join() {

            Ok(Ok(())) => {

                log::debug!(target: "test", "Node {} shutdown completed", self.id);

            }

            Ok(Err(e)) => {

                log::warn!(target: "test", "Node {} runtime error during shutdown: {}", self.id, e);

            }

            Err(_) => {

                log::warn!(target: "test", "Node {} thread panicked during shutdown", self.id);

            }

        }

        // Shutdown the handle with error handling to prevent panic during cleanup

        if let Err(e) = unsafe { ManuallyDrop::take(&mut self.handle) }.shutdown() {

            log::warn!(target: "test", "Failed to shutdown node {}: {}", self.id, e);

        }

        // Join the thread with error handling to prevent panic during cleanup

        match unsafe { ManuallyDrop::take(&mut self.thread) }.join() {

            Ok(Ok(())) => {

                log::debug!(target: "test", "Node {} shutdown completed", self.id);

            }

            Ok(Err(e)) => {

                log::warn!(target: "test", "Node {} runtime error during shutdown: {}", self.id, e);

            }

            Err(_) => {

                log::warn!(target: "test", "Node {} thread panicked during shutdown", self.id);

            }

        }

    fn entry(&mut self, id: ResourceId) -> Entry<'_, ResourceId, Peer> {

    pub fn drain<R: RangeBounds<usize>>(&mut self, range: R) -> std::vec::Drain<'_, T> {

    ) -> Result<&mut FetchState, TryFetchError<'_>> {

use std::env;

use std::process::Command;

fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Set a build-time `GIT_HEAD` env var which includes the commit id;

    // such that we can tell which code is running.

    let hash = env::var("GIT_HEAD").unwrap_or_else(|_| {

        Command::new("git")

            .arg("rev-parse")

            .arg("--short")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or("unknown".into())

    });

    let version = if let Ok(version) = env::var("RADICLE_VERSION") {

        version

    } else {

        "pre-release".to_owned()

    };

    // Set a build-time `SOURCE_DATE_EPOCH` env var which includes the commit time.

    let commit_time = env::var("SOURCE_DATE_EPOCH").unwrap_or_else(|_| {

        Command::new("git")

            .arg("log")

            .arg("-1")

            .arg("--pretty=%ct")

            .arg("HEAD")

            .output()

            .ok()

            .and_then(|output| {

                if output.status.success() {

                    String::from_utf8(output.stdout).ok()

                } else {

                    None

                }

            })

            .unwrap_or(0.to_string())

    });

    println!("cargo::rustc-env=RADICLE_VERSION={version}");

    println!("cargo::rustc-env=SOURCE_DATE_EPOCH={commit_time}");

    println!("cargo::rustc-env=GIT_HEAD={hash}");

    Ok(())

}

    fn reader(&self, starting_at: usize) -> Cursor<'_>;

    fn reader(&self, starting_at: usize) -> Cursor<'_> {

    fn reader(&self, starting_at: usize) -> Cursor<'_> {

            // Use our more reliable terminal size detection instead of the broken viewport() function

            if let Some((cols, rows)) = get_terminal_size() {

                Some(Self::max(Size::new(cols, rows)))

            } else {

                // Fallback to viewport if our detection fails

                Some(Self::max(viewport().unwrap_or(Size::MAX)))

            }

    /// Print this element to stdout, automatically using a pager if there are too many lines.

    /// This method is preferred over `print()` when you want automatic paging behavior.

    fn print_with_pager(&self) -> io::Result<()> {

        // Only use pager if we're on a terminal and not in tests

        if !io::stdout().is_terminal() || cfg!(test) {

            // Not on a terminal or running in tests, just print normally

            self.print();

            return Ok(());

        }

        // Get the actual content size using UNBOUNDED constraint

        let element_rows = self.size(Constraint::UNBOUNDED).rows;

        // Try to get terminal size to determine if paging is needed

        if let Some((_, terminal_rows)) = get_terminal_size() {

            // Use pager if the element is too tall for the terminal

            if element_rows > terminal_rows {

                return crate::pager::run(self);

            }

        }

        // Otherwise, just print normally

        self.print();

        Ok(())

    }

    fn print_with_pager(&self) -> io::Result<()> {

        self.deref().print_with_pager()

    }

    fn print_with_pager(&self) -> io::Result<()> {

        (*self).print_with_pager()

    }

    elem: &(impl Element + ?Sized),

/// Get terminal size with fallback methods

pub fn get_terminal_size() -> Option<(usize, usize)> {

    // First try crossterm

    if let Some(size) = crate::viewport() {

        // Validate the size - if it's too small, it's probably wrong

        if size.rows >= 10 && size.cols >= 20 {

            return Some((size.cols, size.rows));

        }

    }

    // Fallback to environment variables

    if let (Ok(lines), Ok(cols)) = (std::env::var("LINES"), std::env::var("COLUMNS")) {

        if let (Ok(lines), Ok(cols)) = (lines.parse::<usize>(), cols.parse::<usize>()) {

            if lines >= 10 && cols >= 20 {

                return Some((cols, lines));

            }

        }

    }

    // Fallback to stty command

    if let Ok(output) = std::process::Command::new("stty").arg("size").output() {

        if let Ok(output_str) = String::from_utf8(output.stdout) {

            let parts: Vec<&str> = output_str.split_whitespace().collect();

            if parts.len() == 2 {

                if let (Ok(lines), Ok(cols)) =

                    (parts[1].parse::<usize>(), parts[0].parse::<usize>())

                {

                    if lines >= 10 && cols >= 20 {

                        return Some((cols, lines));

                    }

                }

            }

        }

    }

    // Final fallback: assume reasonable defaults for modern terminals

    Some((80, 24))

}

pub mod pager;

use std::io::{self, IsTerminal};

use std::process::{Command, Stdio};

use crate::element::{self, get_terminal_size, Constraint, Element};

/// Output the given element through a pager, if necessary.

/// If it fits within the screen, don't run it through a pager.

pub fn run(elem: &(impl Element + ?Sized)) -> io::Result<()> {

    // Only use pager if we're on a terminal and not in tests

    if !io::stdout().is_terminal() || cfg!(test) {

        // Not on a terminal or running in tests, just write directly to stdout

        return element::write_to(elem, &mut io::stdout(), Constraint::UNBOUNDED);

    }

    // Note: We don't need to create a constraint here since we use UNBOUNDED when rendering to pager

    // The pager itself handles width constraints

    let Some((_, _rows)) = get_terminal_size() else {

        return element::write_to(elem, &mut io::stdout(), Constraint::UNBOUNDED);

    };

    // Get the actual content size using UNBOUNDED constraint

    let element_rows = elem.size(Constraint::UNBOUNDED).rows;

    // Check if the element fits within the terminal

    if let Some((_, terminal_rows)) = get_terminal_size() {

        // If the element fits within the terminal, don't use pager

        if element_rows <= terminal_rows {

            return element::write_to(elem, &mut io::stdout(), Constraint::UNBOUNDED);

        }

    }

    // Get the pager command, but validate it's a real pager

    let pager = std::env::var("PAGER")

        .ok()

        .or_else(|| std::env::var("LESS").ok())

        .or_else(|| Some("more".to_string()));

    // Validate that the pager is a real pager, not a shell command

    let pager = if let Some(ref pager_cmd) = pager {

        if pager_cmd.contains("sh -c") || pager_cmd.contains("head") || pager_cmd.contains("cat") {

            // PAGER appears to be a shell command, fall back to 'more' (safer with colors)

            "more".to_string()

        } else {

            pager_cmd.clone()

        }

    } else {

        "more".to_string()

    };

    let Some(parts) = shlex::split(&pager) else {

        // Fallback to 'more' if pager parsing fails

        let mut child = Command::new("more")

            .stdin(Stdio::piped())

            .stdout(Stdio::inherit())

            .stderr(Stdio::inherit())

            .spawn()?;

        let writer = child.stdin.as_mut().unwrap();

        let result = element::write_to(elem, writer, Constraint::UNBOUNDED);

        child.wait()?;

        match result {

            Err(e) if e.kind() == io::ErrorKind::BrokenPipe => {}

            Err(e) => return Err(e),

            Ok(_) => {}

        }

        return Ok(());

    };

    let Some((program, args)) = parts.split_first() else {

        // Fallback to 'more' if pager parsing fails

        let mut child = Command::new("more")

            .stdin(Stdio::piped())

            .stdout(Stdio::inherit())

            .stderr(Stdio::inherit())

            .spawn()?;

        let writer = child.stdin.as_mut().unwrap();

        let result = element::write_to(elem, writer, Constraint::UNBOUNDED);

        child.wait()?;

        match result {

            Err(e) if e.kind() == io::ErrorKind::BrokenPipe => {}

            Err(e) => return Err(e),

            Ok(_) => {}

        }

        return Ok(());

    };

    let mut child = Command::new(program)

        .stdin(Stdio::piped())

        .stdout(Stdio::inherit())

        .stderr(Stdio::inherit())

        .args(args)

        .spawn()?;

    let writer = child.stdin.as_mut().unwrap();

    // Use UNBOUNDED constraint when rendering to pager to preserve table formatting

    // The pager itself will handle width constraints

    let result = element::write_to(elem, writer, Constraint::UNBOUNDED);

    child.wait()?;

    match result {

        // This error is expected when the pager is exited.

        Err(e) if e.kind() == io::ErrorKind::BrokenPipe => {}

        Err(e) => return Err(e),

        Ok(_) => {}

    }

    Ok(())

}

        // If the constraint is effectively UNBOUNDED (max is Size::MAX), use a reasonable maximum width

        // This preserves table formatting when rendering to pager without making it excessively wide

        if c.max == Size::MAX {

            // Use a reasonable maximum width (e.g., 120 columns) to preserve formatting

            // but avoid making the table excessively wide

            let max_width = 120;

            if cols > max_width {

                return Size::new(max_width, rows);

            }

            return Size::new(cols, rows);

        }

        // Otherwise, apply the constraint

    ) -> Result<IdentityMut<'_, R>, RepositoryError> {

                std::slice::from_ref(&ux_label),

    ) -> Result<Merged<'_, R>, Error>

        pub fn id(remote: &RemoteId) -> Namespaced<'_> {

        pub fn id_root(remote: &RemoteId) -> Namespaced<'_> {

        pub fn sigrefs(remote: &RemoteId) -> Namespaced<'_> {

pub fn parse_ref_namespaced<T>(s: &str) -> Result<(T, format::Qualified<'_>), RefError>

pub fn parse_ref<T>(s: &str) -> Result<(Option<T>, format::Qualified<'_>), RefError>

pub fn head(repo: &git2::Repository) -> Result<git2::Commit<'_>, git2::Error> {

    pub fn refname(&self) -> &Qualified<'_> {

    ) -> Result<git2::Blob<'_>, DocError> {

    fn blob_at<P: AsRef<Path>>(&self, commit: Oid, path: P) -> Result<git2::Blob<'_>, git_ext::Error>;

    fn blob(&self, oid: Oid) -> Result<git2::Blob<'_>, git_ext::Error>;

    fn head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError>;

    fn canonical_head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError>;

    ) -> Result<git2::Reference<'_>, git_ext::Error>;

    fn commit(&self, oid: Oid) -> Result<git2::Commit<'_>, git::ext::Error>;

    fn revwalk(&self, head: Oid) -> Result<git2::Revwalk<'_>, git2::Error>;

    ) -> Result<Vec<(Qualified<'_>, Oid)>, git::ext::Error>;

    fn blob_at<P: AsRef<Path>>(&self, commit: Oid, path: P) -> Result<git2::Blob<'_>, git::Error> {

    fn blob(&self, oid: Oid) -> Result<git2::Blob<'_>, git::Error> {

    ) -> Result<git2::Reference<'_>, git::Error> {

    fn commit(&self, oid: Oid) -> Result<git2::Commit<'_>, git::Error> {

    fn revwalk(&self, head: Oid) -> Result<git2::Revwalk<'_>, git2::Error> {

    ) -> Result<Vec<(Qualified<'_>, Oid)>, git::ext::Error> {

    fn head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError> {

    fn canonical_head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError> {

    fn head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError> {

    fn canonical_head(&self) -> Result<(Qualified<'_>, Oid), RepositoryError> {

    fn commit(&self, oid: Oid) -> Result<git2::Commit<'_>, git_ext::Error> {

    fn revwalk(&self, head: Oid) -> Result<git2::Revwalk<'_>, git2::Error> {

    ) -> Result<git2::Blob<'_>, git_ext::Error> {

    fn blob(&self, oid: git_ext::Oid) -> Result<raw::Blob<'_>, ext::Error> {

    ) -> Result<git2::Reference<'_>, git_ext::Error> {

    ) -> Result<Vec<(fmt::Qualified<'_>, Oid)>, git::ext::Error> {

    pub fn path(&self) -> &git::Qualified<'_> {

pub fn populate(repo: &git2::Repository, scale: usize) -> Vec<git::Qualified<'_>> {

    fn head(&self) -> Result<(fmt::Qualified<'_>, Oid), RepositoryError> {

    fn canonical_head(&self) -> Result<(fmt::Qualified<'_>, Oid), RepositoryError> {

    fn commit(&self, oid: Oid) -> Result<git2::Commit<'_>, git_ext::Error> {

    fn revwalk(&self, _head: Oid) -> Result<git2::Revwalk<'_>, git2::Error> {

    fn blob(&self, _oid: Oid) -> Result<git2::Blob<'_>, git_ext::Error> {

    ) -> Result<git2::Blob<'_>, git_ext::Error> {

    ) -> Result<git2::Reference<'_>, git_ext::Error> {

    ) -> Result<Vec<(fmt::Qualified<'_>, Oid)>, git::ext::Error> {