Git multi-repository workspace management tool
Project description
This is a tool for managing a workspace containing multiple git repositories.
Although generally all software architects agree that version control is essential to software development, the community is split on what is best for large-scale projects, especially those which heavily reuse components. There are many different opinions (for example, see [1], [2], [3], and [4]) but they generally fall into one of two camps:
monorepo – one monolithic repository containing everything
multiple repos – split project into many repositories, each managing a single component
For those whose projects which adopt the philosophy of multiple repos, mugit is used in concert with git to manage the overall project workspace.
The root directory of the workspace, itself managed as a git repository, includes a manifest file. This is an XML file describing which folders in the workspace are themselves git repositories. For each of these, the manifest holds configuration metadata:
upstream URL, from which to clone the repository and to where to push changes
which branch to check out
whether or not to keep the repository pinned, or pointed to a specific revision even if the branch changes (e.g. new commits are added upstream)
Multiple manifest files may exist in a project. Typically one manifest is used during normal development to keep all components up to date on their configured branches, and another manifest (with all repositories pinned) is used to mark what revisions of each component together constitute the last release or snapshot of the overall project.
Installation
pip install mugit – download and install from PyPI
pip install mugit-1.0.0-py2.py3-none-any.whl – install from local wheel file
pip install -e . – install in editable mode from mugit source folder
Usage
mugit [COMMAND] --help – get more help overall or for a specific command
mugit select [-c] <MANIFEST> – select manifest to use in other mugit commands
mugit pull [-c] – clone missing repositories and fetch/rebase existing ones
mugit status [-c] [-a] – generate report on the state of the workspace
Use -a to list all repositories, not just ones with changes.
mugit update [-c] – update manifest to reflect current workspace state
mugit add [-c] --all | <PATH>.. – add repositories to the manifest
Specify repositories by path or use --all to automatically scan for them.
mugit remove <PATH>.. – remove repositories from the manifest
mugit release <MANIFEST> – create or update a release/snapshot manifest
mugit rename <-l|-r> <OLD_BRANCH> <NEW_BRANCH> [PATH].. – rename existing branches locally and remotely
mugit --version – display tool version information
Many mugit commands use ANSI escape codes to control cursor movement in the console. This works for most terminals, but some (most notably, the Windows command prompt) may need help from the colorama library. The commands which can make use of colorama accept the optional -c argument, which if used, activates colorama.
Creating a New Project
When setting up a new project, use mugit select to choose the name of the manifest. The selected manifest is tracked in the .git/config of the root project repository.
After creating or cloning project components, use mugit add -a to scan the workspace for repositories, adding an entry for each into the manifest. This creates the manifest XML file if it didn’t exist previously. Note that newly created components will have no upstream URL and will be skipped in all pulls and remote checks.
mkdir FooBar cd FooBar git init mkdir Foo mkdir Bar git clone https://example.com/Utilites.git cd Foo git init git commit --allow-empty -m "Initial Revision" cd ../Bar git init git commit --allow-empty -m "Initial Revision" cd .. mugit select main mugit add -a git add main.xml git commit -m "Initial Revision"
To add individual components later, create or clone them, and then pass their paths to mugit add to update the manifest. Remember to commit the manifest change to the root project repository.
mkdir Spam cd Spam git init git commit --allow-empty -m "Initial Revision" cd .. mugit select main mugit add Spam git add main.xml git commit -m "Add Spam"
When a new component is initially published, use mugit update to update the manifest to include the upstream URL. Remember to commit the manifest change to the root project repository.
cd Foo git remote add origin https://example.com/foo.git git push --set-upstream origin master cd .. mugit update git add main.xml git commit -m "Foo now published at example.com"
Cloning an Upstream Project
Use mugit select followed by mugit pull to initially clone all components in a project.
git clone https://example.com/FooBar.git cd FooBar mugit select main mugit pull
Checking Status
Use mugit status whenever unsure about whether there are local changes, or to check if there are other changes upstream. Normally, only components found to have local or remote changes will be reported. Use the -a option to force all components to be included in the report.
mugit status -a
Downloading Updates
Use mugit pull to fetch upstream changes. The changes are first fetched into the remote tracking branch. The working branch is then rebased onto the remote tracking branch, resulting in a fast-forward (if there were no local changes) or a rebase (if there were local changes).
It’s best to check the status with mugit status first to make sure there are no local untracked or staged changes which might interfere with a rebase.
mugit status mugit pull
Making a Release
Use mugit release to create a special copy of the selected manifest where all components are pinned, or marked with their current commit SHA1 code listed in the manifest. This is useful for recording the exact revisions of all components used to form a specific snapshot or release of the project.
mugit release release git add release.xml git commit -m "Release 1.12.7" git tag "1.12.7"
Checking Out a Release
A generated manifest can be used later with mugit select to check out the exact revisions of all components in the manifest that were present when that manifest was generated, even if component branches have moved in the interim.
Note that each component ise put into a headless state, even if the revision checked out happens to still be at the head of the configured branch.
mugit select release
License/Warranty
This tool is made available under the MIT license.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
See the file LICENSE.txt for more information.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mugit-1.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d564aac5a06b76c7c60c4bacea5ba1c2f2b02412ce80358531952e3c07545436 |
|
MD5 | 5231a9e48be8d3809b964eb7b17fb575 |
|
BLAKE2b-256 | dfe57968a6ccdc2b1deefcc9376671505b631f77f925911927c49d0dc985655e |