highlight tracking relationship

Author: bill-auger

README.md

@@ -2,10 +2,35 @@
 
 By default, the `git-branch-status` command shows the divergence relationship between branches for which the upstream differs from it's local counterpart.
 
-A number of command-line switches exist selecting various output modes to compare any or all local or remote branches.
+A number of command-line switches exist, selecting various reports that compare any or all local or remote branches.
+
 
 ![git-branch-status screenshot][scrot]
 
+
+#### Notes regarding the screenshot above:
+
+* This is showing the exhaustive '--all' report. Other reports are constrained (see 'USAGE' below).
+* The "local <-> upstream" section is itemizing all local branches. In this instance:
+  * The local branch 'deleteme' has no remote tracking branch.
+  * The local branch 'kd35a' is tracking remote branch 'kd35a/master'.
+  * The local branch 'knovoselic' is tracking remote branch 'knovoselic/master'.
+  * The local branch 'master' is tracking remote branch 'origin/master'.
+* The "local <-> kd35a" section is itemizing all branches on the 'kd35a' remote. In this instance:
+  * The local branch 'master' is 2 commits behind and 24 commits ahead of the remote branch 'kd35a/master'.
+* The "local <-> knovoselic" section is itemizing all branches on the 'knovoselic' remote. In this instance:
+  * The local branch 'master' is 4 commits behind and 24 commits ahead of the remote branch 'knovoselic/master'.
+* The "local <-> origin" section is itemizing all branches on the 'origin' remote. In this instance:
+  * The remote branch 'origin/delete-me' is not checked-out locally.
+  * The remote branch 'origin/master' is tracked by the local branch 'master'.
+* The asterisks to the left of local 'master' branch names indicate the current working branch.
+* The blue branch names indicate a tracking relationship between a local and it's upstream branch.
+* The "local <-> upstream" section relates tracking branches while remote-specific sections relate identically named branches. This distinction determines the semantics of the green "Everything is synchronized" message.
+  * In the "local <-> upstream" section, this indicates that all local branches which are tracking an upstream are up-to-date with their respective upstream counterparts.
+  * In remote-specific sections, this indicates that all local branches which have the same name as some branch on this remote are up-to-date with that remote branch.
+  * In single branch reports, this indicates that the local branch is up-to-date with it's upstream counterpart if it is tracking an upstream; otherwise this will always be shown.
+
+
 ```
 USAGE:
 
@@ -70,6 +95,7 @@ EXAMPLES:
     | 1999-12-31 tracked | (even)     | (even) | 2000-01-01 origin/tracked |
 ```
 
+
 _NOTE: please direct comments, bug reports, feature requests, or PRs to one of the upstream repos:_
 * [https://github.com/bill-auger/git-branch-status/issues/][github-issues]
 * [https://notabug.org/bill-auger/git-branch-status/issues/][notabug-issues]

git-branch-status

@@ -99,11 +99,13 @@ USAGE_MSG
 
 readonly MAX_COL_W=27 # should be >= 12
 readonly CWHITE='\033[0;37m'
+readonly CRED='\033[0;31m'
 readonly CGREEN='\033[0;32m'
 readonly CYELLOW='\033[1;33m'
-readonly CRED='\033[0;31m'
+readonly CBLUE='\033[1;34m'
 readonly CEND='\033[0m'
 readonly CDEFAULT=$CWHITE
+readonly CTRACKING=$CBLUE
 readonly CAHEAD=$CYELLOW
 readonly CBEHIND=$CRED
 readonly CEVEN=$CGREEN
@@ -139,7 +141,9 @@ declare -a remote_colors=()
 
 function GetRefs # (refs_dir)
 {
-  git for-each-ref --format="%(refname:short) %(upstream:short)" $1 2> /dev/null
+  refs_dir=$1
+
+  git for-each-ref --format="%(refname:short) %(upstream:short)" $refs_dir 2> /dev/null
 }
 
 function GetLocalRefs
@@ -167,6 +171,13 @@ function GetCurrentBranch
   git rev-parse --abbrev-ref HEAD
 }
 
+function GetUpstreamBranch # (local_branch)
+{
+  local_branch=$1
+
+  git rev-parse --abbrev-ref $local_branch@{upstream} 2> /dev/null
+}
+
 function IsCurrentBranch # (branch_name)
 {
   branch=$1
@@ -229,6 +240,7 @@ function GenerateReport # (local_branch_name remote_branch_name)
 {
   local_branch=$1
   remote_branch=$2
+  upstream_branch=$(GetUpstreamBranch $local_branch)
   does_local_exist=$(DoesBranchExist $local_branch)
 
   # filter branches per CLI arg
@@ -249,8 +261,9 @@ function GenerateReport # (local_branch_name remote_branch_name)
        # filter branches by status
        (($SHOW_ALL_UPSTREAM)) || (($n_differences)) || return
 
-       # set data for branches with upstream
-       local_color=$CDEFAULT
+       # set data for branches with remote counterparts
+       [ "$remote_branch" == "$upstream_branch" ] && color=$CTRACKING || color=$CDEFAULT
+       local_color=$color
        if (($n_behind))
        then behind_msg="(behind$JOIN_CHAR$n_behind)" ; behind_color=$CBEHIND ;
        else behind_msg="(even)"                      ; behind_color=$CEVEN   ;
@@ -259,7 +272,7 @@ function GenerateReport # (local_branch_name remote_branch_name)
        then ahead_msg="(ahead$JOIN_CHAR$n_ahead)"    ; ahead_color=$CAHEAD   ;
        else ahead_msg="(even)"                       ; ahead_color=$CEVEN    ;
        fi
-       remote_color=$CDEFAULT
+       remote_color=$color
   elif (($does_local_exist)) && [ -z "$remote_branch" ] && (($SHOW_ALL_LOCAL))
   then # dummy data for local branches with no upstream counterpart
        local_color=$CDEFAULT
@@ -375,9 +388,9 @@ esac
 readonly FILTER_BRANCH=$branch
 readonly SHOW_DATES=$show_dates
 readonly SHOW_ALL=$show_all
-readonly SHOW_ALL_LOCAL=$(($show_all    + $show_all_local))    # also show branches that have no upstream
-readonly SHOW_ALL_UPSTREAM=$(($show_all + $show_all_upstream)) # also show branches that are up to date
-readonly SHOW_ALL_REMOTE=$(($show_all   + $show_all_remote))   # also show branches that have no local
+readonly SHOW_ALL_LOCAL=$(($show_all    + $show_all_local))    # show local branches that are not tracking any upstream
+readonly SHOW_ALL_UPSTREAM=$(($show_all + $show_all_upstream)) # show local branches that are synchronized with their upstream
+readonly SHOW_ALL_REMOTE=$(($show_all   + $show_all_remote))   # show all remote branches
 
 
 # compare local branches status to their upstreams
@@ -390,11 +403,10 @@ PrintReport "local <-> upstream"
 # compare other remote branches status to local branches
 for remote_repo in `git remote`
 do
-  while read remote_branch ; do
-    local_branch=${remote_branch#$remote_repo/}
-    upstream_branch=`git rev-parse --abbrev-ref $local_branch@{upstream} 2> /dev/null`
+  while read remote_branch
+  do local_branch=${remote_branch#$remote_repo/}
 
-    [ "$remote_branch" != "$upstream_branch" ] && GenerateReport $local_branch $remote_branch
+     GenerateReport $local_branch $remote_branch
   done < <(GetRemoteRefs $remote_repo)
 
   PrintReport "local <-> $remote_repo"