completion: add proper public __git_complete

When __git_complete was introduced, it was meant to be temporarily, while
a proper guideline for public shell functions was established
(tentatively _GIT_complete), but since that never happened, people
in the wild started to use __git_complete, even though it was marked as
not public.

Eight years is more than enough wait, let's mark this function as
public, and make it a bit more user-friendly.

So that instead of doing:

  __git_complete gk __gitk_main

The user can do:

  __git_complete gk gitk

And instead of:

  __git_complete gf _git_fetch

Do:

  __git_complete gf git_fetch

Backwards compatibility is maintained.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 1150d4bf4427d398ce08942b74cb090b83343cd2..4b1f4264a64e6d8bf4c09fae8573f86726f5cad1 100644 (file)
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -29,6 +29,15 @@
 # tell the completion to use commit completion.  This also works with aliases
 # of form "!sh -c '...'".  For example, "!sh -c ': git commit ; ... '".
 #
+# If you have a command that is not part of git, but you would still
+# like completion, you can use __git_complete:
+#
+#   __git_complete gl git_log
+#
+# Or if it's a main command (i.e. git or gitk):
+#
+#   __git_complete gk gitk
+#
 # Compatible with bash 3.2.57.
 #
 # You can set the following environment variables to influence the behavior of
@@ -3497,10 +3506,7 @@ __git_func_wrap ()
        $1
 }
 
-# Setup completion for certain functions defined above by setting common
-# variables and workarounds.
-# This is NOT a public function; use at your own risk.
-__git_complete ()
+___git_complete ()
 {
        local wrapper="__git_wrap${2}"
        eval "$wrapper () { __git_func_wrap $2 ; }"
@@ -3508,13 +3514,33 @@ __git_complete ()
                || complete -o default -o nospace -F $wrapper $1
 }
 
-__git_complete git __git_main
-__git_complete gitk __gitk_main
+# Setup the completion for git commands
+# 1: command or alias
+# 2: function to call (e.g. `git`, `gitk`, `git_fetch`)
+__git_complete ()
+{
+       local func
+
+       if __git_have_func $2; then
+               func=$2
+       elif __git_have_func __$2_main; then
+               func=__$2_main
+       elif __git_have_func _$2; then
+               func=_$2
+       else
+               echo "ERROR: could not find function '$2'" 1>&2
+               return 1
+       fi
+       ___git_complete $1 $func
+}
+
+___git_complete git __git_main
+___git_complete gitk __gitk_main
 
 # The following are necessary only for Cygwin, and only are needed
 # when the user has tab-completed the executable name and consequently
 # included the '.exe' suffix.
 #
 if [ "$OSTYPE" = cygwin ]; then
-       __git_complete git.exe __git_main
+       ___git_complete git.exe __git_main
 fi

diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
index c0b4380eae930738ee51a49514e2ed981a629334..c4a7758409b39cb35e779f0fd942bc5532d02ad1 100755 (executable)
--- a/t/t9902-completion.sh
+++ b/t/t9902-completion.sh
@@ -2382,10 +2382,22 @@ test_expect_success 'sourcing the completion script clears cached --options' '
 
 test_expect_success '__git_complete' '
        unset -f __git_wrap__git_main &&
+
        __git_complete foo __git_main &&
        __git_have_func __git_wrap__git_main &&
+       unset -f __git_wrap__git_main &&
+
        __git_complete gf _git_fetch &&
-       __git_have_func __git_wrap_git_fetch
+       __git_have_func __git_wrap_git_fetch &&
+
+       __git_complete foo git &&
+       __git_have_func __git_wrap__git_main &&
+       unset -f __git_wrap__git_main &&
+
+       __git_complete gd git_diff &&
+       __git_have_func __git_wrap_git_diff &&
+
+       test_must_fail __git_complete ga missing
 '
 
 test_done