Mothership is a "meta" repository that brings together my core machine scripts, configurations, and dotfiles. Each project is a Git submodule, an independent repository connected here to form a unified hub for managing my development environment.

Clone this repository, then pull in the "fleet" with git submodule update --init --recursive.

• Purpose
• Usage
• Submodules
  • Deploying submodules
    • Python deployment script
  • Updating submodules
  • Adding submodules
  • Removing submodules
  • Change submodule remote
  • Move a submodule in the repository
• Taskfile tasks
• Troubleshooting
  • Submodule updates in pipeline not applied locally
• Links

I use git to manage a lot of my configurations, scripts, and tools (like my CLI swiss army knife syst). Instead of cloning each of my "core" repositories individually, I can clone this repository and extract the submodules to their own paths.

This repository started as a way for me to practice working with Git submodules, and has turned into my configuration hub.

Clone the repository and initialize submodules:

git clone [email protected]:redjax/Mothership # or https://github.com/redjax/Mothership.git
cd Mothership
git submodule update --init --recursive

Alternatively, you can clone & initialize in 1 step:

git clone --recurse-submodules <mothership-repo-url>

If you want to always pull submodule changes when they are updated, set the repository's submodule.recurse to true:

git config submodule.recurse true

Table of the submodules found in the modules/ directory

The Mothership can deploy submodules to paths on the filesystem by "cloning" the submodule to that path. This initializes a standalone repository with the Mothership repository's path as its remote.

For example, to deploy the Ansible module to ~/Ansible:

git clone . ~/Ansible

If you cd ~/Ansible and run git remote -v, you will see the remote is the local Mothership repository's path:

git remote -v
origin  /path/to/Mothership/modules/Ansible/. (fetch)
origin  /path/to/Mothership/modules/Ansible/. (push)

You can leave this configuration as-is, so you will need to update the Mothership's submodules before doing git pull to update the local repository. This centralizes updates, and can help control which version is checked out locally, which can be useful for app configurations.

You can also change the remote back to the module's original repository. For example, set the ~/Ansible repository's remote back to [email protected]:redjax/Ansible.git:

git remote set-url origin "[email protected]:redjax/git_dir.git"
git checkout main

This separates the repository clone from the Mothership completely. It is as if you ran git clone https://github.com/redjax/Ansible.git.

The do_deployment.py script can clone repositories to paths on the host, automating the process of cloning out of the Mothership repository and optionally setting the remote back to the submodule's origin.

Start by creating a deploy.json file (see the example.deploy.json file for the structure):

{
    "repositories": [
        {
            "name": "",
            "target": "",
            "branch": "",
            "mothership_remote": false
        }
    ]
}

• name should match one of the submodule paths in the modules/ directory.
• target is the path on the current machine where you want the cloned repository to exist.
• branch (default should be main) sets the branch to checkout after cloning.
• mothership_remote is a boolean value. When true, the submodule's remote will be the path where you cloned Mothership (i.e. ~/Mothership).
  • If you leave "mothership_remote": true, the cloned repository will be pointed back at the Mothership directory.
  • This means to pull updates, you need to cd back to the Mothership remote and update the submodules, then cd to the cloned repository and run git pull.
  • This can help to control updates to configurations; you won't accidentally pull changes until you switch back to the Mothership repository and pull the submodule.

Run the scripts/deploy/do_deployment.py script with -c /path/to/your/deploy.json.

Run this command to recursively pull the main branch of each submodule:

git submodule foreach git pull origin main

git submodule add https://github.com/youruser/repo_name.git local/path/to/repo_name

git submodule deinit -f local/path/to/repo_name
git rm local/path/to/repo_name
rm -rf .git/modules/local/path/to/repo_name

## Commit changes to MetaRepo
git commit -m "Remove local/path/to/repo_name submodule"

Edit .gitmodules file, update the URL of the submodule, then run the following to update MetaRepo:

git submodule sync
git submodule update --init --recursive

The easiest method is to use git mv:

git mv old/path/to/submodule new/path/to/submodule

Doing this moves the submodule directory, updates the .gitmodules file with the new path, and adjusts internal Git config as needed.

After moving a submodule, commit like this:

git add .gitmodules
git add -u
git commit -m "Move submodule to new path"

The Taskfile.yml file defines tasks/automations for go-task/task. This allows for powerful automation, and can be used locally or in pipelines.

To see a list of tasks that can be run, use:

task -l

When the pipeline that updates submodules runs and pulls changes on the remote, you need to also pull the submodule changes locally. This can be done with git pull --recurse-submodules, or you can set the local repo to always pull submodule changes on a git pull with:

git config submodule.recurse true

• Git docs: submodules
• FreeCodeCamp: How to use Git submodules - explained with examples
• Atlassian docs: Git submodules
• HowToGeek: What are submodules, and how do you use them?