Replaces "subpath" with "branch"

In favor of a more widely used varaible, the subpath variable has
been replaced with branch. In preparation for branch support in
overlay.xml files.

layman.8.txt: An example of an overlay.xml with a branch in it has
been added for users along with pointers to using the variable.

16 files changed, 74 insertions, 63 deletions

diff --git a/doc/layman.8.txt b/doc/layman.8.txt
index fa75fac..0819570 100644
--- a/doc/layman.8.txt
+++ b/doc/layman.8.txt
@@ -445,6 +445,37 @@ Example 1. An example overlays.xml file
 </repositories>
 -------------------------------------------
 
+Example 2. An example overlays.xml file with a branch
+
+-------------------------------------------
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
+<repositories xmlns="" version="1.0">
+<repo quality="experimental" status="official">
+    <name><hardened-development></name>
+    <description><Development Overlay for Hardened Gcc 4.x Toolchain></description>
+    <homepage>http://git.overlays.gentoo.org/gitweb/?p=proj/hardened-dev.git;a=summary</homepage>
+    <owner type="project">
+       <email>hardened@gentoo.org</email>
+    </owner>
+    <source type="git">git://git.overlays.gentoo.org/proj/hardened-dev.git</source>
+    <branch>uclibc</branch>
+    <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/hardened-dev.git;a=atom</feed>
+</repo>
+</repositories>
+
+Users can specify a branch for an overlay, given one actually exists.
+This logic is applicable to CVS overlays as well and the branch variable
+is comparable to specifying a subpath for a CVS repository.
+
+VCS types where the use of "branch" is supported is as follows:: 
+-  CVS
+-  Tar
+-  Git
+-  Mercurial
+However, for CVS and Tar overlays, the branch will be treated as a subpath.
+If you use the branch variable with any other overlay types aside from the ones
+listed, it will be ignored.
 
 ADDING AN OVERLAY LOCALLY
 ~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/layman/api.py b/layman/api.py
index 1d50adf..a86970f 100755
--- a/layman/api.py
+++ b/layman/api.py
@@ -236,7 +236,7 @@ class LaymanAPI(object):
                     'irc': overlay.irc,
                     'description': overlay.description,
                     'feeds': overlay.feeds,
-                    'sources': [(e.src, e.type, e.subpath) \
+                    'sources': [(e.src, e.type, e.branch) \
                         for e in overlay.sources],
                     #'src_uris': [e.src for e in overlay.sources],
                     'src_uris': overlay.source_uris(),
diff --git a/layman/overlays/bzr.py b/layman/overlays/bzr.py
index 162ba40..ea3e787 100644
--- a/layman/overlays/bzr.py
+++ b/layman/overlays/bzr.py
@@ -47,7 +47,7 @@ class BzrOverlay(OverlaySource):
 
         super(BzrOverlay, self).__init__(parent,
             config, _location, ignore)
-        self.subpath = None
+        self.branch = None
 
     def _fix_bzr_source(self, source):
         '''
diff --git a/layman/overlays/cvs.py b/layman/overlays/cvs.py
index bf54921..a8c6abb 100644
--- a/layman/overlays/cvs.py
+++ b/layman/overlays/cvs.py
@@ -47,25 +47,9 @@ class CvsOverlay(OverlaySource):
     def __init__(self, parent, config, _location, ignore = 0):
 
         super(CvsOverlay, self).__init__(parent, config, _location, ignore)
-        self.subpath = None
+        self.branch = None
 
 
-    def __eq__(self, other):
-        res = super(CvsOverlay, self).__eq__(other) \
-            and self.subpath == other.subpath
-        return res
-
-    def __ne__(self, other):
-        return not self.__eq__(other)
-
-    # overrider
-    def to_xml_hook(self, repo_elem):
-        if self.subpath:
-            _subpath = ET.Element('subpath')
-            _subpath.text = self.subpath
-            repo_elem.append(_subpath)
-            del _subpath
-
     def add(self, base):
         '''Add overlay.'''
 
@@ -84,7 +68,7 @@ class CvsOverlay(OverlaySource):
         if len(cfg_opts):
             args.append(cfg_opts)
         args.append(self.parent.name)
-        args.append(self.subpath)
+        args.append(self.branch)
 
         return self.postsync(
             self.run_command(self.command(), args, cwd=base,
diff --git a/layman/overlays/darcs.py b/layman/overlays/darcs.py
index 6bacb7b..53966c6 100644
--- a/layman/overlays/darcs.py
+++ b/layman/overlays/darcs.py
@@ -46,7 +46,7 @@ class DarcsOverlay(OverlaySource):
 
         super(DarcsOverlay, self).__init__(parent, config,
             _location, ignore)
-        self.subpath = None
+        self.branch = None
 
     def add(self, base):
         '''Add overlay.'''
diff --git a/layman/overlays/g_common.py b/layman/overlays/g_common.py
index 2f33803..f3eb58d 100644
--- a/layman/overlays/g_common.py
+++ b/layman/overlays/g_common.py
@@ -46,7 +46,7 @@ class GCommonOverlay(OverlaySource):
         #split source into driver and remote uri.
         self.driver=self.src[:self.src.find(' ')]
         self.remote_uri=self.src[self.src.find(' ')+1:]
-        self.subpath = None
+        self.branch = None
 
     def add(self, base):
         '''Add overlay.'''
diff --git a/layman/overlays/g_sorcery.py b/layman/overlays/g_sorcery.py
index 6156008..19bfe18 100644
--- a/layman/overlays/g_sorcery.py
+++ b/layman/overlays/g_sorcery.py
@@ -47,7 +47,7 @@ class GSorceryOverlay(OverlaySource):
         #split source into backend and repository.
         self.backend=self.src[:self.src.find(' ')]
         self.repository=self.src[self.src.find(' ')+1:]
-        self.subpath = None
+        self.branch = None
 
     def add(self, base):
         '''Add overlay.'''
diff --git a/layman/overlays/git.py b/layman/overlays/git.py
index 5e99a65..2f4bd61 100644
--- a/layman/overlays/git.py
+++ b/layman/overlays/git.py
@@ -44,7 +44,8 @@ class GitOverlay(OverlaySource):
     def __init__(self, parent, config, _location, ignore = 0):
         super(GitOverlay, self).__init__(parent, config,
             _location, ignore)
-        self.subpath = None
+        self.branch = None
+
 
     def _fix_git_source(self, source):
         '''
diff --git a/layman/overlays/mercurial.py b/layman/overlays/mercurial.py
index 9f7d45c..7a5fe08 100644
--- a/layman/overlays/mercurial.py
+++ b/layman/overlays/mercurial.py
@@ -48,7 +48,7 @@ class MercurialOverlay(OverlaySource):
 
         super(MercurialOverlay, self).__init__(parent,
             config, _location, ignore)
-        self.subpath = None
+        self.branch = None
 
     def _fix_mercurial_source(self, source):
         '''
diff --git a/layman/overlays/overlay.py b/layman/overlays/overlay.py
index d3d81e2..72c5d53 100755
--- a/layman/overlays/overlay.py
+++ b/layman/overlays/overlay.py
@@ -130,6 +130,14 @@ class Overlay(object):
             raise Exception('Overlay from_xml(), "' + self.name + \
                 'is missing a "name" entry!')
 
+        _branch = xml.find('branch')
+        if _branch != None and _branch.text:
+            self.branch = encode(_branch.text.strip())
+        elif 'branch' in xml.attrib:
+            self.branch = encode(xml.attrib['branch'])
+        else:
+            self.branch = ''
+
         _sources = xml.findall('source')
         # new xml format
         if _sources != []:
@@ -158,14 +166,6 @@ class Overlay(object):
 
         self.sources = [create_overlay_source(e) for e in _sources]
 
-        _subpath = xml.find('subpath')
-        if _subpath != None:
-            self.subpath = encode(_subpath.text.strip())
-        elif 'subpath' in xml.attrib:
-            self.subpath = encode(xml.attrib['subpath'])
-        else:
-            self.subpath = ''
-
         _owner = xml.find('owner')
         if _owner == None:
             _email = None
@@ -331,6 +331,11 @@ class Overlay(object):
         else:
             self.irc = None
 
+        _branch = overlay['branch']
+        if _branch != None:
+            self.branch = encode(_branch)
+        else:
+            self.branch = None
         #xml = self.to_xml()
         # end of from_dict
 
@@ -374,6 +379,10 @@ class Overlay(object):
             homepage = ET.Element('homepage')
             homepage.text = self.homepage
             repo.append(homepage)
+        if self.branch != None:
+            branch = ET.Element('branch')
+            branch.text = self.branch
+            repo.append(branch)
         if self.irc != None:
             irc = ET.Element('irc')
             irc.text = self.irc
diff --git a/layman/overlays/rsync.py b/layman/overlays/rsync.py
index 0fa5b06..407a09e 100644
--- a/layman/overlays/rsync.py
+++ b/layman/overlays/rsync.py
@@ -46,7 +46,7 @@ class RsyncOverlay(OverlaySource):
 
         super(RsyncOverlay, self).__init__(parent, config,
             _location, ignore)
-        self.subpath = None
+        self.branch = None
 
     def add(self, base):
         '''Add overlay.'''
diff --git a/layman/overlays/svn.py b/layman/overlays/svn.py
index 41dd862..c97195b 100644
--- a/layman/overlays/svn.py
+++ b/layman/overlays/svn.py
@@ -51,7 +51,7 @@ class SvnOverlay(OverlaySource):
 
         super(SvnOverlay, self).__init__(
             parent, config, _location, ignore)
-        self.subpath = None
+        self.branch = None
 
     def _fix_svn_source(self, source):
         '''
diff --git a/layman/overlays/tar.py b/layman/overlays/tar.py
index a819475..884d527 100644
--- a/layman/overlays/tar.py
+++ b/layman/overlays/tar.py
@@ -64,9 +64,9 @@ class TarOverlay(OverlaySource):
     >>> source = ET.Element('source', type='tar')
     >>> here = os.path.dirname(os.path.realpath(__file__))
     >>> source.text = 'file://' + here + '/../tests/testfiles/layman-test.tar.bz2'
-    >>> subpath = ET.Element('subpath')
-    >>> subpath.text = 'layman-test'
-    >>> repo[:] = [repo_name, desc, owner, source, subpath]
+    >>> branch = ET.Element('branch')
+    >>> branch.text = 'layman-test'
+    >>> repo[:] = [repo_name, desc, owner, source, branch]
     >>> from layman.config import BareConfig
     >>> config = BareConfig()
     >>> import tempfile
@@ -93,23 +93,8 @@ class TarOverlay(OverlaySource):
 
         self.output = config['output']
         self.proxies = config.proxies
-        self.subpath = None
+        self.branch = None
 
-    def __eq__(self, other):
-        res = super(TarOverlay, self).__eq__(other) \
-            and self.subpath == other.subpath
-        return res
-
-    def __ne__(self, other):
-        return not self.__eq__(other)
-
-    # overrider
-    def to_xml_hook(self, repo_elem):
-        if self.subpath:
-            _subpath = ET.Element('subpath')
-            _subpath.text = self.subpath
-            repo_elem.append(_subpath)
-            del _subpath
 
     def _extract(self, base, tar_url, dest_dir):
         ext = '.tar.noidea'
@@ -171,8 +156,8 @@ class TarOverlay(OverlaySource):
             raise error
 
         if result == 0:
-            if self.subpath:
-                source = temp_path + '/' + self.subpath
+            if self.branch:
+                source = temp_path + '/' + self.branch
             else:
                 source = temp_path
 
@@ -188,8 +173,8 @@ class TarOverlay(OverlaySource):
                                     '\nError was:' + str(error))
                 os.chmod(final_path, 0o755)
             else:
-                raise Exception('Given subpath "' + source + '" does not exist '
-                                ' in the tar package!')
+                raise Exception('The given path (branch setting in the xml)\n' + \
+                    '"%(source)s" does not exist in the tar package!' % ({'source': source}))
 
         try_to_wipe(temp_path)
         return result
diff --git a/layman/tests/external.py b/layman/tests/external.py
index 00e4a82..3505eeb 100755
--- a/layman/tests/external.py
+++ b/layman/tests/external.py
@@ -45,10 +45,11 @@ class Unicode(unittest.TestCase):
         self._overlays_bug(286290)
 
 
-class FormatSubpathCategory(unittest.TestCase):
+class FormatBranchCategory(unittest.TestCase):
     def _run(self, number):
         #config = {'output': Message()}
         config = BareConfig()
+        # Discuss renaming files to "branch-%d.xml"
         filename1 = os.path.join(HERE, 'testfiles',
                 'subpath-%d.xml' % number)
 
diff --git a/layman/tests/testfiles/subpath-1.xml b/layman/tests/testfiles/subpath-1.xml
index ddb0e3e..8ae84c6 100644
--- a/layman/tests/testfiles/subpath-1.xml
+++ b/layman/tests/testfiles/subpath-1.xml
@@ -5,7 +5,7 @@
       contact="b_owner@example.org"
       type="tar"
       src="http://example.org/b.tar.gz"
-      subpath="b_path">
+      branch="b_path">
     <description>b_desc</description>
   </overlay>
   <overlay
@@ -13,7 +13,7 @@
       contact="c_owner@example.org"
       type="cvs"
       src=":pserver:username@example.org:/usr/local/cvs-repository"
-      subpath="c_path">
+      branch="c_path">
     <description>c_desc</description>
   </overlay>
 </layman>
diff --git a/layman/tests/testfiles/subpath-2.xml b/layman/tests/testfiles/subpath-2.xml
index aa11497..b0cb05b 100644
--- a/layman/tests/testfiles/subpath-2.xml
+++ b/layman/tests/testfiles/subpath-2.xml
@@ -8,7 +8,7 @@
       <email>b_owner@example.org</email>
     </owner>
     <source type="tar">http://example.org/b.tar.gz</source>
-    <subpath>b_path</subpath>
+    <branch>b_path</branch>
   </repo>
   <repo>
     <name>c_name</name>
@@ -17,6 +17,6 @@
       <email>c_owner@example.org</email>
     </owner>
     <source type="cvs">:pserver:username@example.org:/usr/local/cvs-repository</source>
-    <subpath>c_path</subpath>
+    <branch>c_path</branch>
   </repo>
 </repositories>