docs: Show how last can be used

We can't quite get git's behavior because it has `last` as both before
and after `--`

examples/git-derive.md

@@ -12,6 +12,7 @@ Usage: git-derive[EXE] <COMMAND>
 
 Commands:
     clone    Clones repos
+    diff     Compare two commits
     push     pushes things
     add      adds things
     stash    
@@ -27,6 +28,7 @@ Usage: git-derive[EXE] <COMMAND>
 
 Commands:
     clone    Clones repos
+    diff     Compare two commits
     push     pushes things
     add      adds things
     stash    
@@ -119,3 +121,32 @@ $ git-derive custom-tool arg1 --foo bar
 Calling out to "custom-tool" with ["arg1", "--foo", "bar"]
 
 ```
+
+Last argument:
+```console
+$ git-derive diff --help
+Compare two commits
+
+Usage: git-derive[EXE] diff [COMMIT] [COMMIT] [-- <PATH>]
+
+Arguments:
+    [COMMIT]    
+    [COMMIT]    
+    [PATH]      
+
+Options:
+    -h, --help    Print help information
+
+$ git-derive diff
+Diffing stage..worktree 
+
+$ git-derive diff ./src
+Diffing stage..worktree ./src
+
+$ git-derive diff HEAD ./src
+Diffing HEAD..worktree ./src
+
+$ git-derive diff HEAD~~ -- HEAD
+Diffing HEAD~~..worktree HEAD
+
+```

examples/git-derive.rs

@@ -1,3 +1,4 @@
+use std::ffi::OsStr;
 use std::ffi::OsString;
 use std::path::PathBuf;
 
@@ -20,6 +21,15 @@ enum Commands {
         /// The remote to clone
         remote: String,
     },
+    /// Compare two commits
+    Diff {
+        #[arg(value_name = "COMMIT")]
+        base: Option<OsString>,
+        #[arg(value_name = "COMMIT")]
+        head: Option<OsString>,
+        #[arg(last = true)]
+        path: Option<OsString>,
+    },
     /// pushes things
     #[command(arg_required_else_help = true)]
     Push {
@@ -68,6 +78,30 @@ fn main() {
         Commands::Clone { remote } => {
             println!("Cloning {}", remote);
         }
+        Commands::Diff {
+            mut base,
+            mut head,
+            mut path,
+        } => {
+            if path.is_none() {
+                path = head;
+                head = None;
+                if path.is_none() {
+                    path = base;
+                    base = None;
+                }
+            }
+            let base = base
+                .as_deref()
+                .map(|s| s.to_str().unwrap())
+                .unwrap_or("stage");
+            let head = head
+                .as_deref()
+                .map(|s| s.to_str().unwrap())
+                .unwrap_or("worktree");
+            let path = path.as_deref().unwrap_or_else(|| OsStr::new(""));
+            println!("Diffing {}..{} {}", base, head, path.to_string_lossy());
+        }
         Commands::Push { remote } => {
             println!("Pushing to {}", remote);
         }

examples/git.md

@@ -10,6 +10,7 @@ Usage: git[EXE] <COMMAND>
 
 Commands:
     clone    Clones repos
+    diff     Compare two commits
     push     pushes things
     add      adds things
     stash    
@@ -25,6 +26,7 @@ Usage: git[EXE] <COMMAND>
 
 Commands:
     clone    Clones repos
+    diff     Compare two commits
     push     pushes things
     add      adds things
     stash    
@@ -117,3 +119,32 @@ $ git custom-tool arg1 --foo bar
 Calling out to "custom-tool" with ["arg1", "--foo", "bar"]
 
 ```
+
+Last argument:
+```console
+$ git diff --help
+Compare two commits
+
+Usage: git[EXE] diff [COMMIT] [COMMIT] [-- <PATH>]
+
+Arguments:
+    [COMMIT]    
+    [COMMIT]    
+    [PATH]      
+
+Options:
+    -h, --help    Print help information
+
+$ git diff
+Diffing stage..worktree 
+
+$ git diff ./src
+Diffing stage..worktree ./src
+
+$ git diff HEAD ./src
+Diffing HEAD..worktree ./src
+
+$ git diff HEAD~~ -- HEAD
+Diffing HEAD~~..worktree HEAD
+
+```

examples/git.rs

@@ -15,6 +15,13 @@ fn cli() -> Command {
                 .arg(arg!(<REMOTE> "The remote to clone"))
                 .arg_required_else_help(true),
         )
+        .subcommand(
+            Command::new("diff")
+                .about("Compare two commits")
+                .arg(arg!(base: [COMMIT]))
+                .arg(arg!(head: [COMMIT]))
+                .arg(arg!(path: [PATH]).last(true)),
+        )
         .subcommand(
             Command::new("push")
                 .about("pushes things")
@@ -51,6 +58,23 @@ fn main() {
                 sub_matches.get_one::<String>("REMOTE").expect("required")
             );
         }
+        Some(("diff", sub_matches)) => {
+            let mut base = sub_matches.get_one::<String>("base").map(|s| s.as_str());
+            let mut head = sub_matches.get_one::<String>("head").map(|s| s.as_str());
+            let mut path = sub_matches.get_one::<String>("path").map(|s| s.as_str());
+            if path.is_none() {
+                path = head;
+                head = None;
+                if path.is_none() {
+                    path = base;
+                    base = None;
+                }
+            }
+            let base = base.unwrap_or("stage");
+            let head = head.unwrap_or("worktree");
+            let path = path.unwrap_or("");
+            println!("Diffing {}..{} {}", base, head, path);
+        }
         Some(("push", sub_matches)) => {
             println!(
                 "Pushing to {}",

src/_cookbook/mod.rs

@@ -26,6 +26,7 @@
 //!   - External subcommands
 //!   - Optional subcommands
 //!   - Default subcommands
+//!   - [`last`][crate::Arg::last]
 //!
 //! pacman-like interface: [builder][pacman]
 //! - Topics: