Git: Changes to History · 25 min · free lesson

Commit Only Reviewed Paths

Construct the selected commit tree.

Core idea

An unselected worktree edit must not silently enter a selected-path commit.

Diagram for Commit Only Reviewed Paths: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises construct the selected commit tree. Its tests demonstrate the stated finite contract.

Understand it

Task Ledger changes its CLI and a private scratch note at the same time. A commit intended to fix CLI parsing should contain the CLI change, leaving the note outside history. The tree to commit begins with HEAD, not with every current worktree file. Apply selected additions, modifications and deletions onto that tree.

A selection can include a deleted path: remove it from the commit tree instead of resurrecting its old text. Unknown selected paths have no effect in this model. An actual Git operation additionally validates file paths, expected HEAD and concurrent editor revisions. The terminal deliberately uses selected-path commits rather than pretending to implement an independent staging area. Desktop Git can use its index; distinguish that workflow from this app profile.

The route project is Task Ledger: first keep a reproducible source history, then expose its data through a CLI and HTTP boundary, persist it in SQL, diagnose failures and prepare a release. This lesson owns one contract in that project. Run the worked example before changing the starter and explain which input makes the tempting shortcut fail.

Terminal practice: Configure git config user.name and user.email, then git commit -m "Validate CLI input" -- src/main.rs; inspect git status afterwards.

The compiler lab is independent of the reading question. Edit solution.rs; the app supplies a separate caller with normal, empty and adversarial inputs. A successful unchanged demonstration does not prove your implementation. After the lab, apply the same contract to the route companion project. Its README separates the on-device adapter from the desktop Cargo/TCP profile.

Read the code

pub fn selected_tree(
    head: &[(&str, &str)],
    work: &[(&str, &str)],
    selected: &[&str],
) -> Vec<(String, String)> {
    let mut tree: std::collections::BTreeMap<String, String> = head
        .iter()
        .map(|(k, v)| (k.to_string(), v.to_string()))
        .collect();
    let work: std::collections::BTreeMap<_, _> =
        work.iter().copied().collect();
    for path in selected {
        if let Some(value) = work.get(path) {
            tree.insert(path.to_string(), value.to_string());
        } else {
            tree.remove(*path);
        }
    }
    tree.into_iter().collect()
}

fn main() {
    assert_eq!(
        selected_tree(
            &[("a", "old"), ("b", "old")],
            &[("a", "new"), ("b", "secret")],
            &["a"]
        ),
        vec![
            ("a".to_owned(), "new".to_owned()),
            ("b".to_owned(), "old".to_owned())
        ],
        "case 1"
    );
    assert_eq!(
        selected_tree(&[], &[("a", "x")], &[]),
        vec![],
        "case 2"
    );
    assert_eq!(
        selected_tree(&[("a", "x")], &[], &["a"]),
        vec![],
        "case 3"
    );
    assert_eq!(
        selected_tree(&[], &[("b", "x")], &["b", "b"]),
        vec![("b".to_owned(), "x".to_owned())],
        "case 4"
    );
    println!("worked example passed");
}

The worked implementation exercises construct the selected commit tree. Its tests demonstrate the stated finite contract.

Practice starter

pub fn selected_tree(head: &[(&str,&str)], work: &[(&str,&str)], selected: &[&str]) -> Vec<(String,String)> {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Return the HEAD tree with only selected paths replaced from the worktree, or removed if selected and missing. Sort by path; paths are unique in each input. Keep the public signature. Open the compiler lab and edit solution.rs; do not edit the private verification caller.

What success looks like: The separate caller accepts the changed solution and rejects unchanged TODO, a wrong implementation and a printed success message.

Check your understanding

Which tree is the starting point for a selected-path commit?

Reveal the answer
  1. HEAD, followed by selected changes
  2. The whole current worktree always enters the commit
  3. The selected filenames without their contents

Starting from the whole worktree includes unrelated edits.

Go deeper

Common misconception: The whole current worktree always enters the commit

An unselected worktree edit must not silently enter a selected-path commit.

  1. Identify the boundary: Construct the selected commit tree. Write down its accepted inputs and observable output.
  2. Exercise the failure: Starting from the whole worktree includes unrelated edits.
  3. Check the independent caller: Return the HEAD tree with only selected paths replaced from the worktree, or removed if selected and missing. Sort by path; paths are unique in each input.

Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.

Connections

  • Review the Exact Change: Distinguish changed, added and deleted paths
  • Switch Without Losing Work: Protect dirty worktrees during checkout