Python Multigit

A Python version of the multigit Bash script.

While the multigit Bash script at simplest-git-subrepos was created for illustration purposes, this one is intended to be a full-fledged implementation.

The general idea is to offer a simple way of managing "workspaces" integrating multiple git repos starting from a top one, and without the need of difficult "arcanes" like git submodules, git-subtree, etc.: you only need to declare your intended layout in a YAML file, and let this script (multigit) do its job. See the simplest-git-subrepos README for a long-wired explanation.

Contents:

1. usage
   1. subrepos' file format
2. development
   1. tests
   2. code documentation
   3. build
   4. publish
   5. CHANGELOG
3. license

usage

This project is published to the PyPI index so, in order to install it you just need to run pip install multigit.

multigit expects a YAML file named subrepos in the current dir (see example). Optionally, if there's no subrepos file in the current dir and the current directory is within a git sandbox, multigit will try to find a subrepos file at the git sandbox's root.

For each defined subrepo within the subrepos file, it will clone/checkout it to the defined relative path. Optionally, it will checkout the given gitref (either commit, branch or tag), provided the repo's local sandbox is "clean" (i.e. no pending modifications).
NOTE: pay attention to the fact that if the gitref you record is a specific commit or tag, the related sandbox will be in disconnected state.

multigit will also recursively look for new subrepos files on the root directory of the repositories it manages.

When working within a git repository, you should make sure your .gitignore file ignores all your subrepos.

This way you just need to manage your repos with git in the standard way, just as if they were individually checked out in isolation.

Run multigit with no options or multigit --help for usage.

_{back to top.}

subrepos' file format

The 'subrepos' file holds a yaml dictionary describing the desired lay-out.

It starts with a subrepos key with a list of entries underneath, each of them describing a repository entry point (see 'subrepos' example for further details). Some detailed explanations follow:

• general description:

  ---
  # High-level structure
  subrepos: # main key
  - [first entry]   # first repository description
  - [second entry]  # second repository description
  - [third entry]   # third repository description
  - [...]           # (more repositories)
  

• each repository entry: Each repository definition requires two mandatory keys and an optional one:
  • repository: (mandatory) the URI to operate the remote repository.
    Its format is just the one you'd use to git clone the repository with same effect, i.e. if you need to pass a username/password for an https site, or a password to decrypt you ssh key, etc. here you'll be requested to do it too.
  • path: (mandatory) the path the repository sandbox will the deployed to, relative to the subrepos file itself.
  • [commit|branch|tag]: (optional) the gitref you want your sandbox to be pinned to.
    • You can provide one of either 'commit', 'branch' or 'tag'.
    • Note that if you provide either a commit or a tag the resulting sandbox will be in a detached head state.
    • If you don't provide this key, your sandbox will track the remote's default branch.

A full (conceptual) example:

---
# Don't forget including your subrepos' roots to .gitignore!
subrepos:
- repo: 'git@github.com:jmnavarrol/python-multigit.git'  # the remote using git+ssh protocol.  It may request your ssh key's password
  path: 'a-subdir'  # it will be cloned to 'subdir/' relative to 'subrepos' file
  # no gitref, so this will track the remote's default branch
- repo: 'https://github.com/jmnavarrol/python-multigit.git'  # the remote using https protocol.  It may request user/password
  path: 'a-subdir/another-subdir'  # it will be cloned to 'a-subdir/subdir/' relative to 'subrepos' file
  branch: 'a-branch'  # the sandbox will track the 'a-branch' branch.

NOTE: Since repositories are listed in an array, order matters: first repository is processed before the second one and so on. This means that you can declare first a repository to be deployed to a subdirectory and then another repository to be deployed to a subdirectory of that first subdirectory and things will behave as expected.
It's usually better that you declare the "deeper" subdirectory within its own 'subrepos' file in the intermediate repository, though.

_{back to top.}

development

This project uses the help of Bash Magic Enviro to configure its development environment.

It creates a Python 3 virtualenv using the companion requirements file.

Once the virtualenv is (automatically) activated, you can run this code just invoking its main script, i.e.: multigit.

_{back to top.}

tests

When adding or modifying tests, preserve these rules:

• keep make test runnable offline,
• prefer local scaffolding over external remotes,
• use mocks only when a condition cannot be reproduced reliably with local Git state.

_{back to top.}

code documentation

Code documentation is produced with the help of Sphinx, with configurations at src/sphinx/. While sphinx includes its own Makefile, HTML doc can be generated from the Makefile at src/, starting at the local src/build/html/index.html file.

You can browse it on-line at https://jmnavarrol.github.io/python-multigit.

_{back to top.}

build

The included Makefile will use Python's Hatch to build both source and binary-based Python eggs. Provided everything went OK, look for packages under the dist/ directory.

Run make to see available make targets.

_{back to top.}

publish

Provided Makefile includes publication targets to both testing and live PyPi services by means of twine. Make sure your ~/.pypi.rc file includes proper entries named [testpypi] and [pypi] respectively. Remember, also, that you can't publish the same version twice to these services, so make sure you udpate the package's version before attempting an upload.

_{back to top.}

License

Python Multigit is made available under the terms of the GPLv3.

See the license file that accompanies this distribution for the full text of the license.

_{back to top.}