https://github.com/pistonite/magoo
A wrapper for `git submodule`
https://github.com/pistonite/magoo
git submodule tools
Last synced: 10 months ago
JSON representation
A wrapper for `git submodule`
- Host: GitHub
- URL: https://github.com/pistonite/magoo
- Owner: Pistonite
- License: mit
- Created: 2023-11-22T04:19:37.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-01T06:53:18.000Z (over 1 year ago)
- Last Synced: 2025-03-25T07:23:53.124Z (11 months ago)
- Topics: git, submodule, tools
- Language: Rust
- Homepage: https://docs.rs/magoo
- Size: 172 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
#  magoo
This  is Magoo, he helps you manage git submodules with ease, like `npm` or `cargo`, but for submodules.
Adding a submodule is easy, but have you ever struggled with:
- How do I update a submodule?
- How do I delete a submodule?
- How do I tell my colleagues how to update their submodules after I update them????
 saves all of us by running the `git` commands for us. He figures out
all the relevant information from the git repository itself. There's no extra files
required and  works out of the box for all git repos with submodules.
 **does not like pipelines**. Please simply let your pipeline
checkout the submodules (recursively if needed). For example, if you are using GitHub Actions:
```yaml
- uses: actions/checkout@v4
with:
submodules: recursive
```
## Install 
###  As a CLI tool
```
cargo install magoo
```
###  As a library
To add  as a dependency:
```
cargo add magoo
```
See https://docs.rs/magoo for more info.
## Use 
 runs `git` commands using sub-processes, so you must have `git` installed on the system.
By default,  checks if the `git` version is supported.
To print what version is supported manually, run:
```
magoo status --git
```
Unsupported versions might work as well, you can let  know with the `--allow-unsupported` flag (note
it needs to be before the subcommand)
```
magoo --allow-unsupported status
```
### Add a submodule
```bash
magoo install URL PATH
```
(`magoo install --help` to see a full list of options)
The arguments for adding a submodule is very similar to [`git submodule add`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-add-bltbranchgt-f--force--nameltnamegt--referenceltrepositorygt--depthltdepthgt--ltrepositorygtltpathgt)
 needs to know the following to add a submodule.:
|Arg|Description|Default|
|-|-|-|
|`URL`| The git URL like `https://github.com/owner/repo`. SSH and relative URLs also work. See [`git submodule add`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-add-bltbranchgt-f--force--nameltnamegt--referenceltrepositorygt--depthltdepthgt--ltrepositorygtltpathgt) for details | URL is required |
|`PATH`| The path in your repo the module should be at | Directory at the top level with the same name as the submodule repo|
|`BRANCH`| The branch to update to when you run `magoo update` | None (`HEAD`) |
|`NAME`| Name to identify the submodule for other commands | same as `PATH` |
It's recommended to always specify the `BRANCH`. Git by default will use the `HEAD` branch, which
is usually not what you want.
The submodule will not be cloned recursively when adding. If you need, run `magoo install` after the `add` to clone the recursive submodules.
### Initialize/pull the submodules
```bash
magoo install
```
 will ensure the submodules are cloned/updated to the commit stored in the index.
You should run `magoo install` every time you pull the changes from others, in case they were updated.
It also deletes submodules that are deleted by others (by running `status --fix`, see below).
By default, submodules are installed recursively, you can use `--no-recursive` to only install the ones specified by the top-level repo.
### Show submodule status
```bash
magoo status [--long] [--fix]
```
 will show you everything he knows about submodules in the current repo.
The `--fix` option will bring the submodule states back to a consistent state that  likes.
The state could be inconsistent if the git files were changed manually or by running
individual `git` commands, or by a remote change.
 will fix the state by either de-initializing the submodule (if possible), or delete the submodule.
### Update submodules
```bash
magoo update
```
This tells  to update all submodules to be sync with the remote `BRANCH` (specified when submodule was added).
See `magoo update --help` for more info.
You can also:
- Update one submodule to the latest
```bash
magoo update NAME
```
- Change the branch and/or URL of a submodule
```bash
magoo update NAME --branch BRANCH --url URL
```
### Remove submodules
```bash
magoo remove NAME
```
 will remove every trace of the submodule, with this single command.
Note: Newer versions of git lets you delete a submodule with `git rm`. However, it doesn't delete the content in
`.git/modules`.  deletes those as well.