Add pathspec support in git-missing (tj#1156)

* feat: Add pathspec support in git-missing

Allow to specify a path to limit the commit difference list. This
improvement allows users to focus on changes in specific directories or
files when comparing branches for missing commits.

* refactor: Improve pathspec handling in git-missing

- Change pathspec from string to array to support multiple pathspecs
- Remove unnecessary 'shift' command in argument processing loop
- Simplify git log command execution by using a single codepath

* chore: Update git-missing docs

* chore: Fix a typo in git-missing docs

Commands.md

@@ -1296,14 +1296,20 @@ Creates a zip archive of the current git repository. The name of the archive wil
 
 ## git missing
 
-Print out which commits are on one branch or the other but not both.
+Print out which commits are on one branch or the other but not both. Optionally, you can specify a path to limit the comparison to a specific directory or file.
 
 ```bash
 $ git missing master
 < d14b8f0 only on current checked out branch
 > 97ef387 only on master
 ```
 
+```bash
+$ git missing master -- src/
+< ed52989 only on current branch, in src/ directory
+> 7988c4b only on master, in src/ directory
+```
+
 ## git lock
 
 Lock a local file `filename`:

bin/git-missing

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
 usage() {
-    echo 1>&2 "usage: git missing [<first branch>] <second branch> [<git log options>]"
+    echo 1>&2 "usage: git missing [<first branch>] <second branch> [<git log options>] [[--] <path>...]"
 }
 
 if [ "${#}" -lt 1 ]
@@ -12,9 +12,20 @@ fi
 
 declare -a git_log_args=()
 declare -a branches=()
+declare -a pathspec=()
+declare parse_path=false
+
 for arg in "$@" ; do
 
+    if [[ $parse_path == true ]]; then
+        pathspec+=("$@")
+        break
+    fi
+
     case "$arg" in
+        --)
+            parse_path=true
+            ;;
         --*)
             git_log_args+=( "$arg" )
             ;;
@@ -38,4 +49,4 @@ else
     exit 1
 fi
 
-git log "${git_log_args[@]}" "$firstbranch"..."$secondbranch" --format="%m %h %s" --left-right
+git log "${git_log_args[@]}" "$firstbranch"..."$secondbranch" --format="%m %h %s" --left-right -- "${pathspec[@]}"

man/git-missing.1

@@ -1,16 +1,16 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-MISSING" "1" "April 2018" "" "Git Extras"
+.TH "GIT\-MISSING" "1" "August 2024" "" "Git Extras"
 .
 .SH "NAME"
 \fBgit\-missing\fR \- Show commits missing from another branch
 .
 .SH "SYNOPSIS"
-\fBgit\-missing\fR [<first branch>] <second branch> [<git log options>]
+\fBgit\-missing\fR [<first branch>] <second branch> [<git log options>] [[\-\-] <path>\.\.\.]
 .
 .SH "DESCRIPTION"
-Shows commits that are in either of two branches but not both\. Useful for seeing what would come across in a merge or push\.
+Shows commits that are in either of two branches but not both\. Useful for seeing what would come across in a merge or push\. Optionally, the comparison can be limited to specific paths\.
 .
 .SH "OPTIONS"
 [<first branch>]
@@ -30,6 +30,12 @@ Second branch to compare\.
 .P
 Any flags that should be passed to \'git log\', such as \-\-no\-merges\.
 .
+.P
+[[\-\-] <path>\.\.\.]
+.
+.P
+Optional path specifications (pathspec) to limit the comparison to specific files or directories\. For more details about the pathspec syntax, see the pathspec entry in gitglossary[7] \fIhttps://git\-scm\.com/docs/gitglossary#Documentation/gitglossary\.txt\-aiddefpathspecapathspec\fR\.
+.
 .SH "EXAMPLES"
 Show commits on either my current branch or master but not both:
 .
@@ -60,11 +66,26 @@ $ git missing foo bar
 .
 .IP "" 0
 .
+.P
+Show commits on either my current branch or master but not both, limited to the src/ directory:
+.
+.IP "" 4
+.
+.nf
+
+$ git missing master \-\- src/
+< ed52989 only on current checked out branch, in src/ directory
+> 7988c4b only on master, in src/ directory
+.
+.fi
+.
+.IP "" 0
+.
 .SH "AUTHOR"
 Written by Nate Jones <\fInate@endot\.org\fR>
 .
 .SH "REPORTING BUGS"
-<\fIhttp://github\.com/tj/git\-extras/issues\fR>
+<\fIhttps://github\.com/tj/git\-extras/issues\fR>
 .
 .SH "SEE ALSO"
-<\fIhttp://github\.com/tj/git\-extras\fR>
+<\fIhttps://github\.com/tj/git\-extras\fR>

man/git-missing.md

@@ -3,12 +3,13 @@ git-missing(1) -- Show commits missing from another branch
 
 ## SYNOPSIS
 
-`git-missing` [<first branch>] <second branch> [<git log options>]
+`git-missing` [<first branch>] <second branch> [<git log options>] [[--] <path>...]
 
 ## DESCRIPTION
 
-  Shows commits that are in either of two branches but not both.  Useful for
-  seeing what would come across in a merge or push.
+  Shows commits that are in either of two branches but not both. Useful for
+  seeing what would come across in a merge or push. Optionally, the comparison
+  can be limited to specific paths.
 
 ## OPTIONS
 
@@ -24,6 +25,12 @@ git-missing(1) -- Show commits missing from another branch
 
   Any flags that should be passed to 'git log', such as --no-merges.
 
+  [[--] <path>...]
+
+  Optional path specifications (pathspec) to limit the comparison to specific
+  files or directories. For more details about the pathspec syntax, see the
+  pathspec entry in [gitglossary[7]](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec).
+
 ## EXAMPLES
 
   Show commits on either my current branch or master but not both:
@@ -38,6 +45,13 @@ git-missing(1) -- Show commits missing from another branch
     < b8f0d14 only on foo
     > f38797e only on bar
 
+  Show commits on either my current branch or master but not both, limited to the
+  src/ directory:
+
+    $ git missing master -- src/
+    < ed52989 only on current checked out branch, in src/ directory
+    > 7988c4b only on master, in src/ directory
+
 ## AUTHOR
 
 Written by Nate Jones &lt;<[email protected]>&gt;