The git show-branch command provides more detailed output than git branch, listing the commits that contribute to one or more branches in roughly reverse chronological order. As with git branch, no options list the topic branches, -r shows remote tracking branches, and -a shows all branches.

Let’s look at an example:

$ git show-branch
! [bug/pr-1] Fix Problem Report 1
 * [dev] Improve the new development
  ! [master] Added Bob's fixes.
---
 *  [dev] Improve the new development
 *  [dev^] Start some new development.
+   [bug/pr-1] Fix Problem Report 1
+*+ [master] Added Bob's fixes.

The git show-branch output is broken down into two sections separated by a line of dashes. The section above the separator lists the names of branches enclosed in square brackets, one per line. Each branch name is associated with a single column of output, identified by either an exclamation mark or—if it is also the current branch—an asterisk. In the example just shown, commits within the branch bug/pr-1 start in the first column, commits within the current branch dev start in the second column, and commits in the third branch master start in the third column. For quick reference, each branch in the upper section is also listed with the first line of the log message from the most recent commit on that branch.

The lower section of output is a matrix stating which commits are present in each branch. Again, each commit is listed with the first log message line from that commit. A commit is present in a branch if there a plus sign (+), an asterisk (*), or a minus sign (–) in that branch’s column. The plus sign indicates the commit is in a branch; the asterisk just highlights the commit as being present on the active branch. The minus sign denotes a merge commit.

For example, both of the following commits are identified by asterisks and are present in the dev branch:

*  [dev] Improve the new development
*  [dev^] Start some new development.

These two commits are not present in any other branch. They are listed in reverse chronological order: the most recent commit is at the top and the oldest commit at the bottom.

Enclosed within square brackets on each commit line, Git also shows you a name for that commit. As already mentioned, Git assigns the branch name to the most recent commit. Previous commits have the same name with trailing caret (^) characters. In Chapter 6, you saw master as the name for the most recent commit and master^ as the name for the penultimate commit. Similarly, dev and dev^ are the two most recent commits on the branch dev.

Although the commits within a branch are ordered, branches themselves are listed in an arbitrary order. This is because all branches have equal status; there is no rule stating that one branch is more important than another.

If the same commit is present in multiple branches, it will have a plus sign or asterisk indicator for each branch. Thus, the last commit shown in the previous output is present in all three branches:

+*+ [master] Added Bob's fixes.

The first plus sign means that the commit is in bug/pr-1, the asterisk means the same commit is in the active branch dev, and the final plus sign means the commit is also in the master branch.

When invoked, git show-branch traverses through all the commits on all branches being shown, stopping the listing on the most recent common commit present on all of them. In this case, Git listed four commits before it found one common to all three branches (Added Bob's fixes.), at which point it stopped.

Stopping at the first common commit is the default heuristic for reasonable behavior. It is presumed that reaching such a common point yields sufficient context to understand how the branches relate to each other. If for some reason you actually want more commit history, use the --more=num option, specifying the number of additional commits you want to see going back in time along the common branch.

The git show-branch command accepts a set of branch names as parameters, allowing you to limit the history shown to those branches. For example, if a new branch named bug/pr-2 is added starting at the master commit, it would look like this:

$ git branch bug/pr-2 master
$ git show-branch
! [bug/pr-1] Fix Problem Report 1
 ! [bug/pr-2] Added Bob's fixes.
  * [dev] Improve the new development
   ! [master] Added Bob's fixes.
----
  *  [dev] Improve the new development
  *  [dev^] Start some new development.
+    [bug/pr-1] Fix Problem Report 1
++*+ [bug/pr-2] Added Bob's fixes.

If you wanted to see the commit history for just the bug/pr-1 and bug/pr-2 branches, you could use:

$ git show-branch bug/pr-1 bug/pr-2

While that might be fine for a few branches, if there were many such branches, naming them all would be quite tedious. Fortunately, Git allows wildcard matching of branch names as well. The same results can be achieved using the simpler bug/* branch wildcard name:

$ git show-branch bug/pr-1 bug/pr-2
! [bug/pr-1] Fix Problem Report 1
 ! [bug/pr-2] Added Bob's fixes.
--
+  [bug/pr-1] Fix Problem Report 1
++ [bug/pr-2] Added Bob's fixes.

$ git show-branch bug/*
! [bug/pr-1] Fix Problem Report 1
 ! [bug/pr-2] Added Bob's fixes.
--
+  [bug/pr-1] Fix Problem Report 1
++ [bug/pr-2] Added Bob's fixes.