Merge pull request #37 from bill-auger/master

git-branch-status new features

Author: jwiegley

git-branch-status-subtree/README.md

@@ -5,10 +5,10 @@ By default, the `git-branch-status` command shows the divergence relationship be
 A number of command-line switches exist, selecting various reports that compare any or all local or remote branches.
 
 
-![git-branch-status screenshot][scrot]
+![git-branch-status screen-shot][scrot]
 
 
-#### Notes regarding the screenshot above:
+#### Notes regarding the screen-shot 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:
@@ -18,18 +18,22 @@ A number of command-line switches exist, selecting various reports that compare
   * 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 remote 'kd35a' has no other branches.
 * 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 remote 'knovoselic' has no other branches.
 * 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 remote branch 'origin/delete-me' may or may not be checked-out locally; but no local branch exists with the name: 'delete-me'.
+  * The local branch 'deleteme' is at the same commit as the remote branch 'origin/deleteme' but this is not a tracking relationship.
+  * The local branch 'master' is tracking the remote branch 'origin/master'.
 * The asterisks to the left of the 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 "... synchronized" messages.
-  * In the "local <-> upstream" section, this indicates that all local branches which are tracking an upstream are synchronized 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 synchronized with that remote branch.
-  * In single branch reports, this indicates that the local branch is tracking an upstream branch and is synchronized with it's upstream counterpart.
-  * In arbitrary branch comparison reports, this indicates that the two compared branches are synchronized with each other.
+* The blue branch names indicate an explicit tracking relationship between a local branch and it's upstream counterpart.
+* The "local <-> upstream" section relates tracking relationships between local branches and their upstream counterparts; while the remote-specific sections relate identically named branches. Tracking relationships may or may not be indicated in the remote-specific sections, depending on whether or not both counterparts also coincidentally have the same branch name.
+* In addition to the local amd remote reports, there are two other reports that are not shown in the screen-shot: a single branch report and an arbitrary branch comparison report. The report context determines the semantics of the green "... synchronized ..." messages which may appear under the respectively appropriate circumstances, as such:
+  * In the "local <-> upstream" section, the green message indicates that all local branches which are tracking an upstream are synchronized with their respective upstream counterparts.
+  * In remote-specific sections, the green message indicates that all local branches which have the same name as some branch on this remote are synchronized with that remote branch. These are not necessarily tracking relationships.
+  * In single branch reports, the green message indicates that the local branch is tracking an upstream branch and is synchronized with it's upstream counterpart.
+  * In arbitrary branch comparison reports, the green message indicates that the two compared branches are synchronized with each other.
 
 
 ```
@@ -38,7 +42,7 @@ USAGE:
   git-branch-status
   git-branch-status [ base-branch-name compare-branch-name ]
   git-branch-status [ -a | --all ]
-  git-branch-status [ -b | --branch ] [filter-branch-name]
+  git-branch-status [ -b | --branch ] [ filter-branch-name ]
   git-branch-status [ -d | --dates ]
   git-branch-status [ -h | --help ]
   git-branch-status [ -l | --local ]
@@ -94,9 +98,9 @@ EXAMPLES:
   # show all local branches - including those synchronized or non-tracking
   $ git-branch-status -l
   $ git-branch-status --local
-    | master         | (even)     | (ahead 1) | origin/master             |
-    | tracked-branch | (even)     | (even)    | origin/tracked-branch     |
-    | local-branch   | n/a        | n/a       | (no upstream)             |
+    | master         | (even)     | (ahead 1) | origin/master         |
+    | tracked-branch | (even)     | (even)    | origin/tracked-branch |
+    | local-branch   | n/a        | n/a       | (no upstream)         |
 
   # show all remote branches - including those not checked-out
   $ git-branch-status -r
@@ -113,11 +117,13 @@ EXAMPLES:
 ```
 
 
-_NOTE: please direct comments, bug reports, feature requests, or PRs to one of the upstream repos:_
+_NOTE: please direct 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]
+* [https://pagure.io/git-branch-status/issues/][pagure-issues]
 
 
-[scrot]:          http://bill-auger.github.io/git-branch-status-scrot.png "git-branch-status screenshot"
+[scrot]:          http://bill-auger.github.io/git-branch-status-scrot.png "git-branch-status screen-shot"
 [github-issues]:  https://github.com/bill-auger/git-branch-status/issues/
 [notabug-issues]: https://notabug.org/bill-auger/git-branch-status/issues/
+[pagure-issues]:  https://pagure.io/git-branch-status/issues/