Merge pull request #113 from jacebrowning/release/v0.10

Release v0.10

CHANGES.md

@@ -1,6 +1,11 @@
 Revision History
 ================
 
+0.10 (2016/04/14)
+-----------------
+
+- Added `show` command to display dependency and internal paths.
+
 0.9 (2016/03/31)
 ----------------
 

Makefile

@@ -11,7 +11,7 @@ endif
 
 # Test settings
 UNIT_TEST_COVERAGE := 73
-INTEGRATION_TEST_COVERAGE := 52
+INTEGRATION_TEST_COVERAGE := 79
 COMBINED_TEST_COVERAGE := 97
 
 # System paths
@@ -119,7 +119,7 @@ depends: depends-ci depends-doc depends-dev
 .PHONY: depends-ci
 depends-ci: env Makefile $(DEPENDS_CI_FLAG)
 $(DEPENDS_CI_FLAG): Makefile
-	$(PIP) install --upgrade pep8 pep257 pylint coverage pytest pytest-describe pytest-expecter pytest-cov pytest-random
+	$(PIP) install --upgrade pep8 pep257 pylint coverage pytest pytest-describe pytest-expecter pytest-cov pytest-random freezegun
 	@ touch $(DEPENDS_CI_FLAG)  # flag to indicate dependencies are installed
 
 .PHONY: depends-doc

docs/interfaces/api.md

@@ -66,7 +66,7 @@ with optional arguments:
 
 ## Uninstall
 
-To delete all source dependencies, call:
+To delete all dependencies, call:
 
 ```python
 gitman.uninstall(root=None, force=False)

docs/interfaces/cli.md

@@ -13,7 +13,7 @@ gitman install
 or filter the dependency list by directory name:
 
 ```sh
-gitman install <dir1> <dir2> <etc.>
+gitman install <name1> <name2> <etc.>
 ```
 
 or limit the traversal of nested dependencies:
@@ -51,7 +51,7 @@ gitman update
 or filter the dependency list by directory name:
 
 ```sh
-gitman update <dir1> <dir2> <etc.>
+gitman update <name1> <name2> <etc.>
 ```
 
 or limit the traversal of nested dependencies:
@@ -86,6 +86,8 @@ or exit with an error if there are any uncommitted changes:
 gitman list --no-dirty
 ```
 
+The `list` command will also record versions in the log file.
+
 ## Lock
 
 To manually record the exact version of each dependency, run:
@@ -97,7 +99,7 @@ gitman lock
 or lock down specific dependencies:
 
 ```sh
-gitman lock <dir1> <dir2> <etc.>
+gitman lock <name1> <name2> <etc.>
 ```
 
 This can be combined with updating dependencies by running:
@@ -114,7 +116,7 @@ gitman install
 
 ## Uninstall
 
-To delete all source dependencies, run:
+To delete all dependencies, run:
 
 ```sh
 gitman uninstall
@@ -126,6 +128,32 @@ If any dependencies contain uncommitted changes, instead run:
 gitman uninstall --force
 ```
 
+## Show
+
+To display the path to the dependency storage location:
+
+```sh
+gitman show
+```
+
+To display the path to a dependency:
+
+```sh
+gitman show <name>
+```
+
+To display the path to the configuration file:
+
+```sh
+gitman show --config
+```
+
+To display the path to the log file:
+
+```sh
+gitman show --log
+```
+
 ## Edit
 
 To open the existing configuration file:

docs/interfaces/plugin.md

@@ -58,7 +58,7 @@ git deps --list
 
 ## Uninstall
 
-To delete all source dependencies, run:
+To delete all dependencies, run:
 
 ```sh
 git deps --uninstall

docs/use-cases/build-integration.md

@@ -0,0 +1,60 @@
+# Build System Integration
+
+GitMan can be invoked from your build system or continuous integration environment. It provides a convenient way to access its internal file and directory paths using the [`show`](../interfaces/cli.md#show) command.
+
+## Makefile
+
+The following example shows one way you might want to call `gitman` from within a Makefile:
+
+```makefile
+.PHONY: all
+all: depends
+
+.PHONY: depends
+depends: $(shell gitman show --log)
+$(shell gitman show --log): $(shell gitman show --config)
+	gitman install
+	make -C $(shell gitman show lib_foo) configure all install
+	make -C $(shell gitman show lib_bar) configure all install
+	gitman list
+
+.PHONY: clean
+clean:
+  gitman uninstall
+```
+
+using a configuration file similar to:
+
+```yaml
+location: sources
+sources:
+- dir: lib_foo
+  repo: https://github.com/example/lib_foo
+  rev: develop
+- dir: lib_bar
+  repo: https://github.com/example/lib_bar
+  rev: master
+sources_locked:
+- dir: lib_foo
+  repo: https://github.com/example/lib_foo
+  rev: 73cb3668d4c9c3388fb21de16c9c3f6217cc0e1c
+- dir: lib_bar
+  repo: https://github.com/example/lib_bar
+  rev: 560ea99953a4b3e393e170e07895d14904eb032c
+```
+
+## Workflow
+
+Running `make depends` performs the following actions:
+
+1. Check the modification times of the configuration and log files
+2. If the configuration file is newer, continue
+3. Install the locked dependency versions
+4. Run `make` inside of each dependency's folder
+5. Update the log file with the current versions of all dependencies
+
+To update your dependencies:
+
+1. Run `gitman update`
+2. Run `make depends`
+3. If the new build passes your tests, commit the new configuration file

gitman/__init__.py

@@ -3,7 +3,7 @@
 import sys
 
 __project__ = 'GitMan'
-__version__ = '0.9'
+__version__ = '0.10'
 
 CLI = 'gitman'
 PLUGIN = 'deps'
@@ -14,7 +14,7 @@
 PYTHON_VERSION = 3, 4
 
 if sys.version_info < PYTHON_VERSION:  # pragma: no cover (manual test)
-    exit("Python {}.{}+ is required.".format(*PYTHON_VERSION))
+    sys.exit("Python {}.{}+ is required.".format(*PYTHON_VERSION))
 
 try:
     # pylint: disable=wrong-import-position

gitman/cli.py

@@ -40,8 +40,7 @@ def main(args=None, function=None):
 
     # Main parser
     parser = argparse.ArgumentParser(prog=CLI, description=DESCRIPTION,
-                                     parents=[debug, project], **shared)
-
+                                     parents=[debug], **shared)
     subs = parser.add_subparsers(help="", dest='command', metavar="<command>")
 
     # Install parser
@@ -50,7 +49,7 @@ def main(args=None, function=None):
                           help=info, parents=[debug, project, depth, options],
                           **shared)
     sub.add_argument('name', nargs='*',
-                     help="list of dependencies (`dir` values) to install")
+                     help="list of dependencies names to install")
     sub.add_argument('-e', '--fetch', action='store_true',
                      help="always fetch the latest branches")
 
@@ -60,7 +59,7 @@ def main(args=None, function=None):
                           help=info, parents=[debug, project, depth, options],
                           **shared)
     sub.add_argument('name', nargs='*',
-                     help="list of dependencies (`dir` values) to update")
+                     help="list of dependencies names to update")
     sub.add_argument('-a', '--all', action='store_true', dest='recurse',
                      help="update all nested dependencies, recursively")
     group = sub.add_mutually_exclusive_group()
@@ -84,7 +83,7 @@ def main(args=None, function=None):
     sub = subs.add_parser('lock', description=info.capitalize() + '.',
                           help=info, parents=[debug, project], **shared)
     sub.add_argument('name', nargs='*',
-                     help="list of dependencies (`dir` values) to lock")
+                     help="list of dependency names to lock")
 
     # Uninstall parser
     info = "delete all installed dependencies"
@@ -93,6 +92,17 @@ def main(args=None, function=None):
     sub.add_argument('-f', '--force', action='store_true',
                      help="delete uncommitted changes in dependencies")
 
+    # Show parser
+    info = "display the path of a dependency or internal file"
+    sub = subs.add_parser('show', description=info.capitalize() + '.',
+                          help=info, parents=[debug, project], **shared)
+    sub.add_argument('name', nargs='*',
+                     help="display the path of this dependency")
+    sub.add_argument('-c', '--config', action='store_true',
+                     help="display the path of the config file")
+    sub.add_argument('-l', '--log', action='store_true',
+                     help="display the path of the log file")
+
     # Edit parser
     info = "open the configuration file in the default editor"
     sub = subs.add_parser('edit', description=info.capitalize() + '.',
@@ -114,13 +124,14 @@ def main(args=None, function=None):
 
 def _get_command(function, namespace):
     args = []
-    kwargs = dict(root=namespace.root)
+    kwargs = {}
     exit_msg = ""
 
-    if namespace.command in ('install', 'update'):
+    if namespace.command in ['install', 'update']:
         function = getattr(commands, namespace.command)
         args = namespace.name
-        kwargs.update(depth=namespace.depth,
+        kwargs.update(root=namespace.root,
+                      depth=namespace.depth,
                       force=namespace.force,
                       clean=namespace.clean)
         if namespace.command == 'install':
@@ -129,19 +140,36 @@ def _get_command(function, namespace):
             kwargs.update(recurse=namespace.recurse,
                           lock=namespace.lock)
         exit_msg = "\n" + "Run again with '--force' to overwrite"
+
     elif namespace.command == 'list':
         function = commands.display
-        kwargs.update(dict(depth=namespace.depth,
-                           allow_dirty=namespace.allow_dirty))
+        kwargs.update(root=namespace.root,
+                      depth=namespace.depth,
+                      allow_dirty=namespace.allow_dirty)
+
     elif namespace.command == 'lock':
         function = getattr(commands, namespace.command)
         args = namespace.name
+        kwargs.update(root=namespace.root)
+
     elif namespace.command == 'uninstall':
         function = commands.delete
-        kwargs.update(force=namespace.force)
+        kwargs.update(root=namespace.root,
+                      force=namespace.force)
         exit_msg = "\n" + "Run again with '--force' to ignore"
+
+    elif namespace.command == 'show':
+        function = commands.show
+        args = namespace.name
+        kwargs.update(root=namespace.root)
+        if namespace.config:
+            args.append('__config__')
+        if namespace.log:
+            args.append('__log__')
+
     elif namespace.command == 'edit':
         function = commands.edit
+        kwargs.update(root=namespace.root)
 
     return function, args, kwargs, exit_msg