git-custom-cli 2.4.0

Fast, keyboard-driven terminal UI for dated Git commits
//! Plain-English glossary for beginner explanations (`ui::explain`, the guide mode).
//! Add terms freely; keep each definition to one or two short sentences.

/// (term, definition). Lookups ignore case.
pub const TERMS: &[(&str, &str)] = &[
    (
        "HEAD",
        "The commit you are on right now. Usually it points at a branch, and moves with it.",
    ),
    (
        "branch",
        "A movable name for a line of work. New commits are added to the branch you are on.",
    ),
    (
        "commit",
        "A saved snapshot of your project with a message describing it. Commits are the steps of your history.",
    ),
    (
        "staging area",
        "The list of changes that will go into your next commit. You choose what to stage.",
    ),
    (
        "index",
        "Another name for the staging area: the list of changes that will go into your next commit.",
    ),
    (
        "working tree",
        "The actual files in your project folder, as you see them now, including unsaved-to-git edits.",
    ),
    (
        "remote",
        "A copy of your repository somewhere else, such as GitHub. You push your work to it and pull from it.",
    ),
    (
        "origin",
        "The default name for the remote you cloned from or first pushed to.",
    ),
    (
        "upstream",
        "The remote branch your branch syncs with, like origin/main. Push and pull use it.",
    ),
    (
        "ahead/behind",
        "Ahead means you have commits the remote lacks (push them). Behind means the remote has commits you lack (pull them).",
    ),
    (
        "detached HEAD",
        "You are on a commit, not a branch. New commits here are easy to lose: create a branch first.",
    ),
    (
        "fast-forward",
        "Moving a branch straight ahead to a newer commit, because nothing diverged. No merge commit is needed.",
    ),
    (
        "merge",
        "Combine the work of another branch into your current branch. Git may ask you to fix conflicts.",
    ),
    (
        "rebase",
        "Replay your commits on top of another base, giving a straight history. It rewrites those commits, so avoid it on shared work.",
    ),
    (
        "cherry-pick",
        "Copy one commit from another branch onto your current branch as a new commit.",
    ),
    (
        "revert",
        "Make a new commit that undoes an earlier commit. History is kept, so it is safe for shared branches.",
    ),
    (
        "reset soft",
        "Move the branch back to another commit but keep all changes staged. Nothing is lost.",
    ),
    (
        "reset mixed",
        "Move the branch back and unstage the changes, but keep your files as they are. Nothing is lost.",
    ),
    (
        "reset hard",
        "Move the branch back and throw away all uncommitted changes in your files. This can lose work.",
    ),
    (
        "stash",
        "A shelf for unfinished changes. Put them away to get a clean tree, and bring them back later.",
    ),
    (
        "tag",
        "A fixed name for one commit, often used for releases like v1.0.",
    ),
    (
        "reflog",
        "A private diary of where your branch tips and HEAD have been. It helps recover commits you thought were lost.",
    ),
    (
        "amend",
        "Replace your latest commit with a fixed-up version, for a better message or a forgotten file.",
    ),
    (
        "force-with-lease",
        "A safer force push: it overwrites the remote only if nobody else pushed since you last looked.",
    ),
    (
        "conflict",
        "Two changes touch the same lines and git cannot choose. You edit the file to pick the result, then continue.",
    ),
    (
        "fetch",
        "Download new commits from the remote without changing your files or branches.",
    ),
    (
        "pull",
        "Fetch from the remote and then bring those commits into your current branch.",
    ),
    (
        "push",
        "Upload your commits to the remote so others can get them.",
    ),
    (
        "clone",
        "Make a full local copy of a remote repository, with all its history.",
    ),
    (
        "fork",
        "Your own copy of someone else's repository on a hosting site, where you can make changes freely.",
    ),
    (
        "hunk",
        "One continuous block of changed lines in a diff. You can stage or discard hunks one at a time.",
    ),
    (
        "blame",
        "Show who last changed each line of a file, and in which commit.",
    ),
    (
        "bisect",
        "Find which commit introduced a bug by testing commits and halving the search each time.",
    ),
    (
        "submodule",
        "A repository nested inside another one, pinned to a specific commit.",
    ),
    (
        "worktree",
        "An extra folder checked out from the same repository, so you can work on two branches at once.",
    ),
    (
        ".gitignore",
        "A file listing patterns of files git should leave alone, such as build output and secrets.",
    ),
    (
        "protected branch",
        "A branch, like main, that gct treats with extra care: no force pushes or deletes without strong confirmation.",
    ),
    (
        "backup ref",
        "A hidden safety copy gct makes before risky actions. It lets you get back to the earlier state.",
    ),
];

/// The definition of `name`, ignoring case and surrounding spaces.
#[allow(dead_code)] // public lookup used by tests and future modes
pub fn term(name: &str) -> Option<&'static str> {
    let name = name.trim();
    TERMS
        .iter()
        .find(|(term, _)| term.eq_ignore_ascii_case(name))
        .map(|(_, definition)| *definition)
}

/// Every term whose name contains `query` (case-insensitive). Empty query returns all terms.
pub fn search(query: &str) -> Vec<(&'static str, &'static str)> {
    let query = query.trim().to_lowercase();
    TERMS
        .iter()
        .filter(|(term, _)| term.to_lowercase().contains(&query))
        .copied()
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn looks_up_terms() {
        assert!(term("head").unwrap().contains("commit"));
        assert!(term(" Staging Area ").is_some());
        assert!(term("nope").is_none());
        assert!(TERMS.len() >= 35);
    }

    #[test]
    fn search_is_case_insensitive_substring() {
        let reset: Vec<_> = search("RESET").iter().map(|(t, _)| *t).collect();
        assert_eq!(reset, ["reset soft", "reset mixed", "reset hard"]);
        assert_eq!(search("").len(), TERMS.len());
        assert!(search("zzzz").is_empty());
        assert!(term("force-WITH-lease").unwrap().contains("force push"));
    }

    #[test]
    fn terms_are_unique_and_filled() {
        for (i, (name, def)) in TERMS.iter().enumerate() {
            assert!(!name.is_empty() && def.len() > 10, "{name}");
            assert!(
                TERMS[..i]
                    .iter()
                    .all(|(n, _)| !n.eq_ignore_ascii_case(name)),
                "dup {name}"
            );
        }
    }
}