Package API

All of the command-line interface functionality is available from the Python package:

import gitman

Init

To generate a sample config for a new project, call:

gitman.init()

Install

To clone/checkout the specified dependencies, call:

gitman.install(*names, root=None, depth=None,
               force=False, fetch=False, clean=True skip_changes=False)

with optional arguments:

  • *names: optional list of dependency source or group names to filter on
  • root: specifies the path to the root working tree
  • depth: number of levels of dependencies to traverse
  • force: indicates uncommitted changes can be overwritten and script errors can be ignored
  • fetch: indicates the latest branches should always be fetched
  • clean: indicates untracked files should be deleted from dependencies
  • skip_changes: indicates dependencies with uncommitted changes should be skipped

Update

If any of the dependencies track a branch (rather than a specific commit), the current upstream version of that branch can be checked out by calling:

gitman.update(*names, root=None, depth=None, recurse=False,
              force=False, clean=True, lock=None, skip_changes=False)

with optional arguments:

  • *names: optional list of dependency source or group names to filter on
  • root: specifies the path to the root working tree
  • depth: number of levels of dependencies to traverse
  • recurse: indicates nested dependencies should also be updated
  • force: indicates uncommitted changes can be overwritten and script errors can be ignored
  • clean: indicates untracked files should be deleted from dependencies
  • lock: indicates updated dependency versions should be recorded
  • skip_changes: indicates dependencies with uncommitted changes should be skipped

List

To display the currently checked out dependencies, call:

gitman.list(root=None, depth=None, allow_dirty=True)

with optional arguments:

  • root: specifies the path to the root working tree
  • depth: number of levels of dependencies to traverse
  • allow_dirty: causes uncommitted changes to be ignored

Lock

To record the exact versions of currently checked out dependencies, call:

gitman.lock(*names, root=None)

with optional arguments:

  • *names: optional list of dependency source or group names to filter on
  • root: specifies the path to the root working tree

and specific versions per source:

  • Each name may be followed by @<sha>, @<branch>, or @<tag>
  • For example:
    • *names = ["source1@abc123", source2@v1.0", "source3"]
    • source1 will be locked to the abc123 SHA if it exists
    • source2 will be locked to the v1.0 tag if it exists
    • source3 will be locked to the currently checked out version

Uninstall

To delete all dependencies, call:

gitman.uninstall(root=None, force=False, keep_location=False)

with optional arguments:

  • root: specifies the path to the root working tree
  • force: indicates uncommitted changes can be overwritten
  • keep_location: indicates that the top level folder should be kept