Adds a #!bash to the top of bash completions so that editors can recognize, it as a bash script. Also adds a few simple comments above commands that, take arguments. The comments are meant to remind editors of potential, problems that can occur when the script is sourced on systems with "set, -u."

Third in a series of patches that make bash completions more robust to different interactive shell configurations and editors.

[PATCH 3/3] Adds a #!bash to the top of bash completions so that editors can recognize
it as a bash script. Also adds a few simple comments above commands that take arguments. The comments are meant to remind editors of potential problems that can occur when the script is sourced on systems with "set -u."

---
 contrib/completion/git-completion.bash |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

index 201f9a6..f8b845a 100755
@@ -1,3 +1,4 @@
+#!bash
 #
 # bash completion support for core Git.
 #

@@ -50,6 +51,8 @@ case "$COMP_WORDBREAKS" in
 *)   COMP_WORDBREAKS="$COMP_WORDBREAKS:"
 esac
 
+# __gitdir accepts 0 or 1 arguments (i.e., location)
+# returns location of .git repo
 __gitdir ()
 {
 	if [ -z "${1-}" ]; then

@@ -67,6 +70,8 @@ __gitdir ()
 	fi
 }
 
+# __git_ps1 accepts 0 or 1 arguments (i.e., format string)
+# returns text to add to bash PS1 prompt (includes branch name)
 __git_ps1 ()
 {
 	local g="$(git rev-parse --git-dir 2>/dev/null)"

@@ -119,6 +124,7 @@ __git_ps1 ()
 	fi
 }
 
+# __gitcomp_1 requires 2 arguments
 __gitcomp_1 ()
 {
 	local c IFS=' '$'\t'$'\n'

@@ -131,6 +137,8 @@ __gitcomp_1 ()
 	done
 }
 
+# __gitcomp accepts 1, 2, 3, or 4 arguments
+# generates completion reply with compgen
 __gitcomp ()
 {
 	local cur="${COMP_WORDS[COMP_CWORD]}"

@@ -150,6 +158,7 @@ __gitcomp ()
 	esac
 }
 
+# __git_heads accepts 0 or 1 arguments (to pass to __gitdir)
 __git_heads ()
 {
 	local cmd i is_hash=y dir="$(__gitdir "${1-}")"

@@ -168,6 +177,7 @@ __git_heads ()
 	done
 }
 
+# __git_tags accepts 0 or 1 arguments (to pass to __gitdir)
 __git_tags ()
 {
 	local cmd i is_hash=y dir="$(__gitdir "${1-}")"

@@ -186,6 +196,7 @@ __git_tags ()
 	done
 }
 
+# __git_refs accepts 0 or 1 arguments (to pass to __gitdir)
 __git_refs ()
 {
 	local i is_hash=y dir="$(__gitdir "${1-}")"

@@ -218,6 +229,7 @@ __git_refs ()
 	done
 }
 
+# __git_refs2 requires 1 argument (to pass to __git_refs)
 __git_refs2 ()
 {
 	local i

@@ -226,6 +238,7 @@ __git_refs2 ()
 	done
 }
 
+# __git_refs_remotes requires 1 argument (to pass to ls-remote)
 __git_refs_remotes ()
 {
 	local cmd i is_hash=y

@@ -470,6 +483,7 @@ __git_aliases ()
 	done
 }
 
+# __git_aliased_command requires 1 argument
 __git_aliased_command ()
 {
 	local word cmdline=$(git --git-dir="$(__gitdir)" \

@@ -482,6 +496,7 @@ __git_aliased_command ()
 	done
 }
 
+# __git_find_subcommand requires 1 argument
 __git_find_subcommand ()
 {
 	local word subcommand c=1

1.6.1.87.g15624

Aside from the message format... OK. The message really should have looked like this from an mbox point of view:

From: Ted Pavlic <[email protected]>
To: git <[email protected]>, Junio C Hamano <[email protected]>
Cc: "Shawn O. Pearce" <[email protected]>
Bcc:
Subject: [PATCH 3/3] bash-completion: Add internal function documentation

Slightly document the internal functions of the bash completion package, so callers are more easily able to determine the expected arguments.

---

Third in a series to improve the bash completion package, so it sucks less.

contrib/completion/git-completion.bash | 15 +++++++++++++++
1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/contrib/completion/git-completion.bash

See how the stuff that doesn't matter to the commit message itself goes after the "---" line? And how the subject is a niceshort, one line summary of the module impacted and the change? These show up in gitk and git shortlog, and thus in the "What's changed in git.git" newsletters Junio publishes. Its important that the subject be really short and sweet. You can put more detail above the "---" line, and it will be included in the commit when Junio applies it.

This is all based on the formatting at the time of commit. Anything up to the first "\n\n" in a commit message goes into the email subject line. The rest goes into the email body, but above the "---" line. You can then edit the buffer before sending to insert non-commit message text after the "---" and before the diff stat.

You can include my Ack'd by line below your Signed-off-by when you resend it.

Shawn.

My rule for this is absolutely no more than 80 characters. Generally, you wouldn't want more than 60 or so, since it is used as the Subject: header and generally has some prefix added.

As shown says, details can go in the rest of the commit message. If you are using more than 60-80 characters even without details, you might think about splitting the patch.

IIRC, multiple "-m" options to "git commit" will be separated by "\n\n", so that's one way to do it if you don't like your $EDITOR for some reason.

Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
[email protected]                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

My rule for *all* of the commit message is "absolutely no more than 76 characters". With more than 76, git log wraps in a 80-column terminal.

Just my 2¢,

Adeodato Simó                                     dato at net.com.org.es
Debian Developer                                  adeodato at debian.org
 
La música es de los que la quieren escuchar y de nadie más.
                -- Andrés Calamaro

Here's my rule:

(add-to-list 'auto-mode-alist

             '("/\\.git/\\(COMMIT\\|TAG\\)_EDITMSG\\'" .
               vcs-message-mode))

(define-derived-mode vcs-message-mode text-mode "VCS-message"
"Major mode for editing commit and tag messages." (auto-fill-mode 1)
(set (make-local-variable 'tab-stop-list)

       (number-sequence 4 100 4))

(setq indent-tabs-mode nil
fill-column 72
truncate-lines t))

That rule could be modified to support .stgit-edit.txt as well.

Ted Pavlic <[email protected]>

  Please visit my ALS association page:
        http://web.alsa.org/goto/tedpavlic
  My family appreciates your support in the fight to defeat ALS.

Adeodato Simó, 13.01.2009:

What about the 50 character limit proposed in the documentation (git-commit, gittutorial, user-manual)?

At the beginning I tried to fulfil this limit, but often it's not easy. So should it be adjusted to a slightly higher value in the documentation or even split into a recommended limit (e.g. 50) and a recommended absolute maximum (e.g. 76)? Hmm, the split wouldn't make sense, I think.

Markus