python-versioneer · foosel · Jun 30, 2015 · Jun 30, 2015 · Jun 30, 2015 · Jun 30, 2015
diff --git a/README.md b/README.md
@@ -231,12 +231,19 @@ information:
   useful to throw an exception in setup.py if this is set, to avoid e.g.
   creating tarballs with a version string of "unknown".
 
+If the underlying VCS supports it and that information is available, this will
+also be included:
+
+* `['branch']`: A string with the VCS branch name the version was built on.
+
 Some variants are more useful than others. Including `full-revisionid` in a
 bug report should allow developers to reconstruct the exact code being tested
 (or indicate the presence of local changes that should be shared with the
 developers). `version` is suitable for display in an "about" box or a CLI
 `--version` output: it can be easily compared against release notes and lists
-of bugs fixed in various releases.
+of bugs fixed in various releases. Augmenting that with the `branch`
+information if it is available will give additional hints during bug reporting
+what kind of setup a user was running.
 
 The installer adds the following text to your `__init__.py` to place a basic
 version in `YOURPROJECT.__version__`:

diff --git a/details.md b/details.md
@@ -22,7 +22,7 @@ It returns `get_versions()["version"]`. See below for what that means.
 
 ## What does get_versions() return?
 
-`get_versions()` returns a small dictionary of rendered version information, which always contains four keys: 
+`get_versions()` returns a small dictionary of rendered version information, which always contains four keys:
 
 | key | description |
 | --- | ---         |
@@ -31,7 +31,13 @@ It returns `get_versions()["version"]`. See below for what that means.
 | `dirty` | A boolean, True if the source tree has local changes. None if unknown. |
 | `error` | None, or a error description string |
 
-`version` will always be a string (`str` on py3, `unicode` on py2): if Versioneer is unable to compute a version, it will be set to `"0+unknown"`. `full-revisionid` will be a str/unicode, or None if that information is not available. `dirty` will be a boolean, or None if unavailable. `error` will be None, or a str/unicode if there was an error.
+It may also contain a fifth key `branch` if that is supported by the selected VCS and the information is available:
+
+| key | description |
+| --- | ---         |
+| `branch` | The name of the branch (for git), or equivalent (for other VCS systems). |
+
+`version` will always be a string (`str` on py3, `unicode` on py2): if Versioneer is unable to compute a version, it will be set to `"0+unknown"`. `full-revisionid` will be a str/unicode, or None if that information is not available. `dirty` will be a boolean, or None if unavailable. `error` will be None, or a str/unicode if there was an error. `branch` will be a str/unicode if that information is available, otherwise it will be unset.
 
 If the `error` key is non-None, that indicates that Versioneer was unable to obtain a satisfactory version string. There are several possibilities:
 
@@ -61,6 +67,8 @@ if versioneer.get_versions()["dirty"]:
 
 `dirty` is most meaningful in from-vcs mode. In from-file mode, it records the dirty status of the tree from which the setup.py build/sdist command was run, and is not affected by subsequent changes to the generated tree. In from-keyword and from-parentdir mode, it will always be `False`.
 
+`branch` might be useful for version display within installed applications, to provide helpful information during error reporting by users.
+
 ## How do I select a 'version-style'?
 
 (note: styles are not yet implemented, and all strings use the `pep440` style)
@@ -110,4 +118,3 @@ The from-keywords mode will only produce `exact-tag` and `full-revisionid`. If t
 | pep440-old   | TAG[.postDIST]     | TAG or ?          | TAG[.postDIST[.dev0]]    | TAG or ?  |
 | git-describe | TAG[-DIST-gHASH]   | TAG or ?          | TAG[-DIST-gHASH][-dirty] | TAG or ?  |
 | long         | TAG-DIST-gHASH     | TAG-gHASH or ?    | TAG-DIST-gHASH[-dirty]   | ?         |
-
diff --git a/src/cmdclass.py b/src/cmdclass.py
@@ -43,6 +43,8 @@ def run(self):
             vers = get_versions(verbose=True)
             print("Version: %s" % vers["version"])
             print(" full-revisionid: %s" % vers.get("full-revisionid"))
+            if "branch" in vers:
+                print(" branch: %s" % vers["branch"])
             print(" dirty: %s" % vers.get("dirty"))
             if vers["error"]:
                 print(" error: %s" % vers["error"])

diff --git a/src/git/from_keywords.py b/src/git/from_keywords.py
@@ -57,6 +57,15 @@ def git_versions_from_keywords(keywords, tag_prefix, verbose):
         tags = set([r for r in refs if re.search(r'\d', r)])
         if verbose:
             print("discarding '%s', no digits" % ",".join(refs-tags))
+
+    branches = [r for r in refs if not r.startswith(TAG)
+                and r != "HEAD" and not r.startswith("refs/")]
+    if verbose:
+        print("likely branches: %s" % ",".join(sorted(branches)))
+    branch = None
+    if branches:
+        branch = branches[0]
+
     if verbose:
         print("likely tags: %s" % ",".join(sorted(tags)))
     for ref in sorted(tags):
@@ -65,10 +74,13 @@ def git_versions_from_keywords(keywords, tag_prefix, verbose):
             r = ref[len(tag_prefix):]
             if verbose:
                 print("picking %s" % r)
-            return {"version": r,
-                    "full-revisionid": keywords["full"].strip(),
-                    "dirty": False, "error": None
-                    }
+
+            result = {"version": r,
+                      "full-revisionid": keywords["full"].strip(),
+                      "dirty": False, "error": None}
+            if branch is not None:
+                result["branch"] = branch
+            return result
     # no suitable tags, so version is "0+unknown", but full hex is still there
     if verbose:
         print("no suitable tags, using unknown + full revision id")

diff --git a/src/git/from_vcs.py b/src/git/from_vcs.py
@@ -52,6 +52,13 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command):
     if dirty:
         git_describe = git_describe[:git_describe.rindex("-dirty")]
 
+    # figure out our branch
+    abbrev_ref_out = run_command(GITS,
+                                 ["rev-parse", "--abbrev-ref", "HEAD"],
+                                 cwd=root)
+    if abbrev_ref_out is not None:
+        pieces["branch"] = abbrev_ref_out.strip()
+
     # now we have TAG-NUM-gHEX or HEX
 
     if "-" in git_describe:

diff --git a/src/render.py b/src/render.py
@@ -162,6 +162,9 @@ def render(pieces, style):
     else:
         raise ValueError("unknown style '%s'" % style)
 
-    return {"version": rendered, "full-revisionid": pieces["long"],
-            "dirty": pieces["dirty"], "error": None}
+    result = {"version": rendered, "full-revisionid": pieces["long"],
+              "dirty": pieces["dirty"], "error": None}
+    if "branch" in pieces and pieces["branch"] is not None:
+        result["branch"] = pieces["branch"]
+    return result
 
diff --git a/test/git/test_git.py b/test/git/test_git.py
@@ -23,16 +23,21 @@ def setUp(self):
         os.mkdir(self.fakegit)
 
     def test_pieces(self):
-        def pv(git_describe, do_error=False, expect_pieces=False):
+        def pv(git_describe, branch="master", do_error=False, expect_pieces=False):
             def fake_run_command(exes, args, cwd=None):
                 if args[0] == "describe":
                     if do_error == "describe":
                         return None
                     return git_describe+"\n"
                 if args[0] == "rev-parse":
-                    if do_error == "rev-parse":
-                        return None
-                    return "longlong\n"
+                    if args[1] == "--abbrev-ref":
+                        if do_error == "ref-parse-branch":
+                            return None
+                        return branch + "\n"
+                    else:
+                        if do_error == "rev-parse":
+                            return None
+                        return "longlong\n"
                 if args[0] == "rev-list":
                     return "42\n"
                 self.fail("git called in weird way: %s" % (args,))
@@ -43,36 +48,41 @@ def fake_run_command(exes, args, cwd=None):
                           pv, "ignored", do_error="describe")
         self.assertRaises(from_vcs.NotThisMethod,
                           pv, "ignored", do_error="rev-parse")
-        self.assertEqual(pv("1f"),
+        self.assertEqual(pv("1f", do_error="ref-parse-branch"),
                          {"closest-tag": None, "dirty": False, "error": None,
                           "distance": 42,
                           "long": "longlong",
                           "short": "longlon"})
+        self.assertEqual(pv("1f"),
+                         {"closest-tag": None, "dirty": False, "error": None,
+                          "distance": 42,
+                          "long": "longlong",
+                          "short": "longlon", "branch": "master"})
         self.assertEqual(pv("1f-dirty"),
                          {"closest-tag": None, "dirty": True, "error": None,
                           "distance": 42,
                           "long": "longlong",
-                          "short": "longlon"})
+                          "short": "longlon", "branch": "master"})
         self.assertEqual(pv("v1.0-0-g1f"),
                          {"closest-tag": "1.0", "dirty": False, "error": None,
                           "distance": 0,
                           "long": "longlong",
-                          "short": "1f"})
+                          "short": "1f", "branch": "master"})
         self.assertEqual(pv("v1.0-0-g1f-dirty"),
                          {"closest-tag": "1.0", "dirty": True, "error": None,
                           "distance": 0,
                           "long": "longlong",
-                          "short": "1f"})
+                          "short": "1f", "branch": "master"})
         self.assertEqual(pv("v1.0-1-g1f"),
                          {"closest-tag": "1.0", "dirty": False, "error": None,
                           "distance": 1,
                           "long": "longlong",
-                          "short": "1f"})
+                          "short": "1f", "branch": "master"})
         self.assertEqual(pv("v1.0-1-g1f-dirty"),
                          {"closest-tag": "1.0", "dirty": True, "error": None,
                           "distance": 1,
                           "long": "longlong",
-                          "short": "1f"})
+                          "short": "1f", "branch": "master"})
 
     def tearDown(self):
         os.rmdir(self.fakegit)