Merge pull request #1 from Pistonite/docs_update

update documentation

.github/workflows/rust.yml

@@ -19,6 +19,9 @@ jobs:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
     - uses: dtolnay/rust-toolchain@stable
     - uses: Swatinem/rust-cache@v2
+    - uses: baptiste0928/cargo-install@v2
+      with:
+        crate: txtpp
     - run: task check
     - run: cargo build --release
     - run: cargo test --release

README.md

@@ -5,8 +5,6 @@
 ![License Badge](https://img.shields.io/github/license/Pistonite/magoo)
 ![Issue Badge](https://img.shields.io/github/issues/Pistonite/magoo)
 
-**In Development. commands left are: remove**
-
 This ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) 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:
@@ -35,68 +33,71 @@ cargo install magoo
 ```
 
 ### ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) As a library
-To include ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) in your rust application, add it as a depedency. See https://docs.rs/magoo for more info.
+To add ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) as a dependency:
+```
+cargo add magoo
+```
+See https://docs.rs/magoo for more info.
 
 ## Use ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp)
 
 ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) runs `git` commands using sub-processes, so you must have `git` installed on the system.
-You can run `magoo status --git` to check what version you have on your system, as well as
-the officially supported `git` versions. Unsupported versions might work as well, ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) just doesn't know.
+To check the version info, run
+```
+magoo status --git
+```
+
+Unsupported versions might work as well, ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) just doesn't know.
 
 
 ### Add a submodule
+```bash
+magoo install URL PATH
+```
+(`magoo install --help` to see a full list of options)
 
-The argument 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)
+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)
 
 ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) needs to know the following to add a submodule.:
 
 |Arg|Description|Default|
 |-|-|-|
-|`URL`| The git URL like `https://github.com/owner/repo`. | URL is Required |
+|`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.
 
-```bash
-magoo install URL --branch BRANCH
-magoo install URL PATH --branch BRANCH
-magoo install URL PATH --branch BRANCH --name NAME --depth DEPTH --force
-```
-
-Run `magoo install help` to see other options
-
-### Initialize the submodules
+### Initialize/pull the submodules
 ```bash
 magoo install
 ```
 ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) 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 --all`, see below).
+It also deletes submodules that are deleted by others (by running `status --fix`, see below).
 
 ### Show submodule status
 ```bash
 magoo status [--long] [--fix]
 ```
-Shows everything ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) knows about submodules in the current repo.
+![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) 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 ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) likes.
 The state could be inconsistent if the git files were changed manually or by running
 individual `git` commands, or by a remote change.
 
-The `--all` option can potentially find more residues.
+![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) will fix the state by either de-initializing the submodule (if possible), or delete the submodule.
 
 ### Update submodules
+```bash
+magoo update
+```
+This tells ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) to update all submodules to be sync with the remote `BRANCH` (specified when submodule was added).
+See `magoo update --help` for more info.
 
-![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) updates the submodule by fetching and checking out the latest updates from the remote, tracked by
-the `BRANCH` specified when you added it.
-
-- Update all submodules to the latest
-   ```bash
-   magoo update
-   ```
+You can also:
 - Update one submodule to the latest
    ```bash
    magoo update NAME
@@ -107,10 +108,10 @@ the `BRANCH` specified when you added it.
    ```
 
 ### Remove submodules
-![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) can remove a submodule with ease:
 ```bash
 magoo remove NAME
 ```
+![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) 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`. ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) deletes those.
+`.git/modules`. ![magoo](https://raw.githubusercontent.com/Pistonite/magoo/main/magoo.webp) deletes those as well.

README.txtpp.md

@@ -51,7 +51,11 @@ TXTPP#include magoo.txt
 ### MAGOO As a library
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
-To include MAGOO in your rust application, add it as a depedency. See https://docs.rs/magoo for more info.
+To add MAGOO as a dependency:
+```
+cargo add magoo
+```
+See https://docs.rs/magoo for more info.
 
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
@@ -60,75 +64,76 @@ TXTPP#include magoo.txt
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
 MAGOO runs `git` commands using sub-processes, so you must have `git` installed on the system.
-You can run `magoo status --git` to check what version you have on your system, as well as
+To check the version info, run
+```
+magoo status --git
+```
+
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
-the officially supported `git` versions. Unsupported versions might work as well, MAGOO just doesn't know.
+Unsupported versions might work as well, MAGOO just doesn't know.
 
 
 ### Add a submodule
+```bash
+magoo install URL PATH
+```
+(`magoo install --help` to see a full list of options)
 
-The argument 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)
+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)
 
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
 MAGOO needs to know the following to add a submodule.:
 
 |Arg|Description|Default|
 |-|-|-|
-|`URL`| The git URL like `https://github.com/owner/repo`. | URL is Required |
+|`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.
 
-```bash
-magoo install URL --branch BRANCH
-magoo install URL PATH --branch BRANCH
-magoo install URL PATH --branch BRANCH --name NAME --depth DEPTH --force
-```
-
-Run `magoo install help` to see other options
-
-### Initialize the submodules
+### Initialize/pull the submodules
 ```bash
 magoo install
 ```
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
 MAGOO 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 --all`, see below).
+It also deletes submodules that are deleted by others (by running `status --fix`, see below).
 
 ### Show submodule status
 ```bash
 magoo status [--long] [--fix]
 ```
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
-Shows everything MAGOO knows about submodules in the current repo.
+MAGOO will show you everything he knows about submodules in the current repo.
 
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
 The `--fix` option will bring the submodule states back to a consistent state that MAGOO likes.
 The state could be inconsistent if the git files were changed manually or by running
 individual `git` commands, or by a remote change.
 
-The `--all` option can potentially find more residues.
+TXTPP#tag MAGOO
+TXTPP#include magoo.txt
+MAGOO will fix the state by either de-initializing the submodule (if possible), or delete the submodule.
 
 ### Update submodules
+```bash
+magoo update
+```
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt
+This tells MAGOO to update all submodules to be sync with the remote `BRANCH` (specified when submodule was added).
+See `magoo update --help` for more info.
 
-MAGOO updates the submodule by fetching and checking out the latest updates from the remote, tracked by
-the `BRANCH` specified when you added it.
-
-- Update all submodules to the latest
-   ```bash
-   magoo update
-   ```
+You can also:
 - Update one submodule to the latest
    ```bash
    magoo update NAME
@@ -139,12 +144,12 @@ the `BRANCH` specified when you added it.
    ```
 
 ### Remove submodules
-TXTPP#tag MAGOO
-TXTPP#include magoo.txt
-MAGOO will remove every trace of a submodule with a single command:
 ```bash
 magoo remove NAME
 ```
+TXTPP#tag MAGOO
+TXTPP#include magoo.txt
+MAGOO will remove every trace of the submodule, with this single command.
 
 TXTPP#tag MAGOO
 TXTPP#include magoo.txt

src/print.rs

@@ -120,7 +120,6 @@ macro_rules! println_warn {
 pub(crate) use println_warn;
 
 /// Print using warning color without a newline
-#[allow(unused_macros)]
 macro_rules! print_warn {
     ($($args:tt)*) => {
         if !$crate::print::is_quiet() {
@@ -133,7 +132,6 @@ macro_rules! print_warn {
         }
     };
 }
-#[allow(unused)]
 pub(crate) use print_warn;
 
 /// Print using error color