Clean-up output from "git show-branch" and document it.

When showing only one branch a lot of default output becomes redundant,
so clean it up a bit, and document what is shown.  Retire the earlier
implementation "git-show-branches-script".

Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/git-show-branch.txt

@@ -0,0 +1,107 @@
+git-show-branch(1)
+==================
+v0.99.4, Aug 2005
+
+NAME
+----
+git-show-branch - Show branches and their commits.
+
+SYNOPSIS
+--------
+'git show-branch [--all] [--heads] [--tags] [--more=<n>] [--merge-base] <reference>...'
+
+DESCRIPTION
+-----------
+Shows the head commits from the named <reference> (or all refs under
+$GIT_DIR/refs/heads), and displays concise list of commit logs
+to show their relationship semi-visually.
+
+OPTIONS
+-------
+<reference>::
+	Name of the reference under $GIT_DIR/refs/.
+
+--all --heads --tags::
+	Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads,
+	and $GIT_DIR/refs/tags, respectively.
+
+--more=<n>::
+	Usually the command stops output upon showing the commit
+	that is the common ancestor of all the branches.  This
+	flag tells the command to go <n> commits beyond that.
+
+--merge-base::
+	Instead of showing the commit list, just act like the
+	'git-merge-base' command except that it can accept more
+	than two heads.
+
+
+OUTPUT
+------
+Given N <references>, the first N lines are the one-line
+description from their commit message.  The branch head that is
+pointed at by $GIT_DIR/HEAD is prefixed with an asterisk '*'
+character while other heads are prefixed with a '!' character.
+
+Following these N lines, one-line log for each commit is
+displayed, indented N places.  If a commit is on the I-th
+branch, the I-th indentation character shows a '+' sign;
+otherwise it shows a space.  Each commit shows a short name that
+can be used as an exended SHA1 to name that commit.
+
+The following example shows three branches, "master", "fixes"
+and "mhf":
+
+------------------------------------------------
+$ git show-branch master fixes mhf
+! [master] Add 'git show-branch'.
+ ! [fixes] Introduce "reset type" flag to "git reset"
+  ! [mhf] Allow "+remote:local" refspec to cause --force when fetching.
+---
+  + [mhf] Allow "+remote:local" refspec to cause --force when fetching.
+  + [mhf~1] Use git-octopus when pulling more than one heads.
+ +  [fixes] Introduce "reset type" flag to "git reset"
+  + [mhf~2] "git fetch --force".
+  + [mhf~3] Use .git/remote/origin, not .git/branches/origin.
+  + [mhf~4] Make "git pull" and "git fetch" default to origin
+  + [mhf~5] Infamous 'octopus merge'
+  + [mhf~6] Retire git-parse-remote.
+  + [mhf~7] Multi-head fetch.
+  + [mhf~8] Start adding the $GIT_DIR/remotes/ support.
++++ [master] Add 'git show-branch'.
+------------------------------------------------
+
+These three branches all forked from a common commit, [master],
+whose commit message is "Add 'git show-branch'.  "fixes" branch
+adds one commit 'Introduce "reset type"'.  "mhf" branch has many
+other commits.
+
+When only one head is given, the output format changes slightly
+to conserve space.  The '+' sign to show which commit is
+reachable from which head and the first N lines to show the list
+of heads being displayed are both meaningless so they are
+omitted.  Also the label given to each commit does not repeat
+the name of the branch because it is obvious.
+
+------------------------------------------------
+$ git show-branch --more=4 master
+[master] Add 'git show-branch'.
+[~1] Add a new extended SHA1 syntax <name>~<num>
+[~2] Fix "git-diff-script A B"
+[~3] git-ls-files: generalized pathspecs
+[~4] Make "git-ls-files" work in subdirectories
+------------------------------------------------
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano.
+
+
+GIT
+---
+Part of the link:git.html[git] suite

Documentation/git.txt

@@ -208,7 +208,7 @@ link:git-pull-script.html[git-pull-script]::
 link:git-commit-script.html[git-commit-script]::
 	Record changes to the repository.
 
-link:git-show-branches-script.html[git-show-branches-script]::
+link:git-show-branch.html[git-show-branch]::
 	Show branches and their commits.
 
 link:git-repack-script.html[git-repack-script]::

Makefile

@@ -71,7 +71,6 @@ SCRIPTS=git git-apply-patch-script git-merge-one-file-script git-prune-script \
 SCRIPTS += git-count-objects-script
 # SCRIPTS += git-send-email-script
 SCRIPTS += git-revert-script
-SCRIPTS += git-show-branches-script
 
 PROG=   git-update-cache git-diff-files git-init-db git-write-tree \
 	git-read-tree git-commit-tree git-cat-file git-fsck-cache \

show-branch.c

@@ -223,6 +223,7 @@ int main(int ac, char **av)
 	int head_path_len;
 	unsigned char head_sha1[20];
 	int merge_base = 0;
+	char **label;
 
 	while (1 < ac && av[1][0] == '-') {
 		char *arg = av[1];
@@ -297,7 +298,8 @@ int main(int ac, char **av)
 	if (merge_base)
 		return show_merge_base(seen, num_rev);
 
-	if (1 < num_rev)
+	/* Show list */
+	if (1 < num_rev) {
 		for (i = 0; i < num_rev; i++) {
 			int j;
 			int is_head = rev_is_head(head_path,
@@ -310,16 +312,28 @@ int main(int ac, char **av)
 			printf("%c [%s] ", is_head ? '*' : '!', ref_name[i]);
 			show_one_commit(rev[i], NULL);
 		}
+		for (i = 0; i < num_rev; i++)
+			putchar('-');
+		putchar('\n');
+	}
+
+	label = ref_name;
 	while (seen) {
 		struct commit *commit = pop_one_commit(&seen);
 		int this_flag = commit->object.flags;
+		static char *obvious[] = { "" };
+
 		if ((this_flag & UNINTERESTING) && (--extra < 0))
 			break;
-		for (i = 0; i < num_rev; i++)
-			putchar((this_flag & (1u << (i + REV_SHIFT)))
-				? '+' : ' ');
-		putchar(' ');
-		show_one_commit(commit, ref_name);
+		if (1 < num_rev) {
+			for (i = 0; i < num_rev; i++)
+				putchar((this_flag & (1u << (i + REV_SHIFT)))
+					? '+' : ' ');
+			putchar(' ');
+		}
+		show_one_commit(commit, label);
+		if (num_rev == 1)
+			label = obvious;
 	}
 	return 0;
 }