summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README.md56
1 files changed, 42 insertions, 14 deletions
diff --git a/README.md b/README.md
index d6efa14..a545b64 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
| | ____ | | | | | ___ |
| | \_ ) | | | | | ( ) |
| (___) |__) (___ | | | ) ( |
-(_______)_______/ )_( |/ \| v0.10
+(_______)_______/ )_( |/ \| v0.11
```
# Gita: a command-line tool to manage multiple git repos
@@ -29,7 +29,14 @@ I also hate to change directories to execute git commands.
![gita screenshot](https://github.com/nosarthur/gita/raw/master/doc/screenshot.png)
-Here the branch color distinguishes 5 situations between local and remote branches:
+In the screenshot, the `gita remote nowhub` command translates to `git remote -v`
+for the `nowhub` repo.
+To see the pre-defined sub-commands, run `gita -h` or take a look at
+[cmds.yml](https://github.com/nosarthur/gita/blob/master/gita/cmds.yml).
+To add your own sub-commands, see the [customization section](#custom).
+To run arbitrary `git` command, see the [superman mode section](#superman).
+
+The branch color distinguishes 5 situations between local and remote branches:
- white: local has no remote
- green: local is the same as remote
@@ -50,32 +57,50 @@ The additional status symbols denote
The bookkeeping sub-commands are
- `gita add <repo-path(s)>`: add repo(s) to `gita`
-- `gita rm <repo-name(s)>`: remove repo(s) from `gita` (won't remove files from disk)
-- `gita group`: show grouping of the repos
-- `gita group <repo-name(s)>`: group repos
-- `gita ungroup <repo-name(s)>`: remove grouping for repos
+- `gita context`: context sub-command
+ - `gita context`: show current context
+ - `gita context none`: remove context
+ - `gita context <group-name>`: set context to `group-name`, all operations then only apply to repos in this group
+- `gita color`: color sub-command
+ - `gita color [ll]`: Show available colors and the current coloring scheme
+ - `gita color set <situation> <color>`: Use the specified color for the local-remote situation
+- `gita group`: group sub-command
+ - `gita group add <repo-name(s)> -n <group-name>`: add repo(s) to a new group or existing group
+ - `gita group [ll]`: display existing groups with repos
+ - `gita group ls`: display existing group names
+ - `gita group rename <group-name> <new-name>`: change group name
+ - `gita group rm <group-name(s)>`: delete group(s)
+- `gita info`: info sub-command
+ - `gita info [ll]`: display the used and unused information items
+ - `gita info add <info-item>`: enable information item
+ - `gita info rm <info-item>`: disable information item
- `gita ll`: display the status of all repos
- `gita ll <group-name>`: display the status of repos in a group
- `gita ls`: display the names of all repos
- `gita ls <repo-name>`: display the absolute path of one repo
- `gita rename <repo-name> <new-name>`: rename a repo
-- `gita info`: display the used and unused information items
+- `gita rm <repo-name(s)>`: remove repo(s) from `gita` (won't remove files from disk)
- `gita -v`: display gita version
-Repo paths are saved in `$XDG_CONFIG_HOME/gita/repo_path` (most likely `~/.config/gita/repo_path`).
-
The delegating sub-commands are of two formats
- `gita <sub-command> [repo-name(s) or group-name(s)]`:
- optional repo or group input, and no input means all repos.
+ optional repo or group input, and **no input means all repos**.
- `gita <sub-command> <repo-name(s) or groups-name(s)>`:
required repo name(s) or group name(s) input
+In either case, the `gita` command translates to running `git <sub-command>` for the corresponding repos.
By default, only `fetch` and `pull` take optional input.
+To see the pre-defined sub-commands, run `gita -h` or take a look at
+[cmds.yml](https://github.com/nosarthur/gita/blob/master/gita/cmds.yml).
+To add your own sub-commands, see the [customization section](#custom).
+To run arbitrary `git` command, see the [superman mode section](#superman).
If more than one repos are specified, the git command will run asynchronously,
with the exception of `log`, `difftool` and `mergetool`, which require non-trivial user input.
+Repo paths are saved in `$XDG_CONFIG_HOME/gita/repo_path` (most likely `~/.config/gita/repo_path`).
+
## Installation
To install the latest version, run
@@ -110,7 +135,7 @@ or
[.gita-completion.zsh](https://github.com/nosarthur/gita/blob/master/.gita-completion.zsh)
and source it in the .rc file.
-## Superman mode
+## <a name='superman'></a> Superman mode
The superman mode delegates any git command/alias.
Usage:
@@ -126,7 +151,7 @@ For example,
- `gita super frontend-repo backend-repo commit -am 'implement a new feature'`
executes `git commit -am 'implement a new feature'` for `frontend-repo` and `backend-repo`
-## Customization
+## <a name='custom'></a> Customization
Custom delegating sub-commands can be defined in `$XDG_CONFIG_HOME/gita/cmds.yml`
(most likely `~/.config/gita/cmds.yml`).
@@ -164,8 +189,11 @@ comaster:
Another customization is the information items displayed by `gita ll`.
The used and unused information items are shown with `gita info` and one can
-create `$XDG_CONFIG_HOME/gita/info.yml` to customize it. For example, the
-default information items setting corresponds to
+create `$XDG_CONFIG_HOME/gita/info.yml` to customize it.
+(I am thinking of hiding all these details from user at the moment, which means
+you probably don't need to read the rest of this section.)
+
+For example, the default information items setting corresponds to
```yaml
- branch