Adding upstream version 0.12.9.upstream/0.12.9

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 55 insertions, 52 deletions

diff --git a/README.md b/README.md
index a545b64..1c9b321 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 | | ____   | |     | |  |  ___  |
 | | \_  )  | |     | |  | (   ) |
 | (___) |__) (___  | |  | )   ( |
-(_______)_______/  )_(  |/     \|   v0.11
+(_______)_______/  )_(  |/     \|   v0.12
 ```
 
 # Gita: a command-line tool to manage multiple git repos
@@ -24,17 +24,18 @@ This tool does two things
 - display the status of multiple git repos such as branch, modification, commit message side by side
 - (batch) delegate git commands/aliases from any working directory
 
-If several repos are related, it helps to see their status together too.
+If several repos are related, it helps to see their status together.
 I also hate to change directories to execute git commands.
 
 ![gita screenshot](https://github.com/nosarthur/gita/raw/master/doc/screenshot.png)
 
 In the screenshot, the `gita remote nowhub` command translates to `git remote -v`
-for the `nowhub` repo.
+for the `nowhub` repo, even though we are at the `blog` 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).
+To run arbitrary shell command, see the [shell mode section](#shell).
 
 The branch color distinguishes 5 situations between local and remote branches:
 
@@ -47,6 +48,8 @@ The branch color distinguishes 5 situations between local and remote branches:
 The choice of purple for ahead and yellow for behind is motivated by
 [blueshift](https://en.wikipedia.org/wiki/Blueshift) and [redshift](https://en.wikipedia.org/wiki/Redshift),
 using green as baseline.
+You can change the color scheme using the `gita color` sub-command.
+See the [customization section](#custom).
 
 The additional status symbols denote
 
@@ -57,6 +60,7 @@ The additional status symbols denote
 The bookkeeping sub-commands are
 
 - `gita add <repo-path(s)>`: add repo(s) to `gita`
+- `gita clone <config-file>`: clone repos in `config-file` (generated by `gita freeze`) to current directory.
 - `gita context`: context sub-command
     - `gita context`: show current context
     - `gita context none`: remove context
@@ -64,12 +68,14 @@ The bookkeeping sub-commands are
 - `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 freeze`: print information of all repos such as URL, name, and path.
 - `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 group rmrepo <repo-name(s)> -n <group-name>`: remove repo(s) from existing group
 - `gita info`: info sub-command
     - `gita info [ll]`: display the used and unused information items
     - `gita info add <info-item>`: enable information item
@@ -82,22 +88,24 @@ The bookkeeping sub-commands are
 - `gita rm <repo-name(s)>`: remove repo(s) from `gita` (won't remove files from disk)
 - `gita -v`: display gita version
 
-The delegating sub-commands are of two formats
+The `git` 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**.
 - `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.
+They translate to `git <sub-command>` for the corresponding repos.
+By default, only `fetch` and `pull` take optional input. In other words,
+`gita fetch` and `gita pull` apply to all repos.
 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 add your own sub-commands or override the default behaviors, 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.
+If more than one repos are specified, the `git` command runs 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`).
 
@@ -109,8 +117,7 @@ To install the latest version, run
 pip3 install -U gita
 ```
 
-If development mode is preferred,
-download the source code and run
+If you prefer development mode, download the source code and run
 
 ```
 pip3 install -e <gita-source-folder>
@@ -123,8 +130,8 @@ then you can put the following line in the `.bashrc` file.
 alias gita="python3 -m gita"
 ```
 
-Windows users may need to enable the ANSI escape sequence in terminal, otherwise
-the branch color won't work.
+Windows users may need to enable the ANSI escape sequence in terminal for
+the branch color to work.
 See [this stackoverflow post](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) for details.
 
 ## Auto-completion
@@ -133,11 +140,11 @@ Download
 [.gita-completion.bash](https://github.com/nosarthur/gita/blob/master/.gita-completion.bash)
 or
 [.gita-completion.zsh](https://github.com/nosarthur/gita/blob/master/.gita-completion.zsh)
-and source it in the .rc file.
+and source it in the corresponding rc file.
 
 ## <a name='superman'></a> Superman mode
 
-The superman mode delegates any git command/alias.
+The superman mode delegates any `git` command or alias.
 Usage:
 
 ```
@@ -151,8 +158,25 @@ 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`
 
+## <a name='shell'></a> Shell mode
+
+The shell mode delegates any shell command.
+Usage:
+
+```
+gita shell [repo-name(s) or group-name(s)] <any-shell-command>
+```
+
+Here `repo-name(s)` or `group-name(s)` are optional, and their absence means all repos.
+For example,
+
+- `gita shell ll` lists contents for all repos
+- `gita shell repo1 mkdir docs` create a new directory `docs` in repo1
+
 ## <a name='custom'></a> Customization
 
+### user-defined sub-command using yaml file
+
 Custom delegating sub-commands can be defined in `$XDG_CONFIG_HOME/gita/cmds.yml`
 (most likely `~/.config/gita/cmds.yml`).
 And they shadow the default ones if name collisions exist.
@@ -167,15 +191,15 @@ stat:
   help: show edit statistics
 ```
 
-which executes `git diff --stat`.
+which executes `git diff --stat` for the specified repo(s).
 
-If the delegated git command is a single word, the `cmd` tag can be omitted.
+If the delegated `git` command is a single word, the `cmd` tag can be omitted.
 See `push` for an example.
 To disable asynchronous execution, set the `disable_async` tag to be `true`.
 See `difftool` for an example.
 
-If you want a custom command to behave like `gita fetch`, i.e., to apply
-command to all repos if nothing is specified,
+If you want a custom command to behave like `gita fetch`, i.e., to apply the
+command to all repos when no repo is specified,
 set the `allow_all` option to be `true`.
 For example, the following snippet creates a new command
 `gita comaster [repo-name(s)]` with optional repo name input.
@@ -187,11 +211,17 @@ comaster:
   help: checkout the master branch
 ```
 
-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.
-(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.)
+### customize the local/remote relationship coloring displayed by the `gita ll` command
+
+You can see the default color scheme and the available colors via `gita color`.
+To change the color coding, use `gita color set <situation> <color>`.
+The configuration is saved in `$XDG_CONFIG_HOME/gita/color.yml`.
+
+### customize information displayed by the `gita ll` command
+
+You can customize the information displayed by `gita ll`.
+The used and unused information items are shown with `gita info`, and the
+configuration is saved in `$XDG_CONFIG_HOME/gita/info.yml`.
 
 For example, the default information items setting corresponds to
 
@@ -200,28 +230,13 @@ For example, the default information items setting corresponds to
 - commit_msg
 ```
 
-To create your own information items, define a dictionary called `extra_info_items`
-in `$XDG_CONFIG_HOME/gita/extra_repo_info.py`. It should map strings to functions,
-where the strings are the information item names and the functions take repo path
-as input. A trivial example is shown below.
-
-```python
-def get_delim(path: str) -> str:
-    return '|'
-
-extra_info_items = {'delim': get_delim}
-```
-
-If it works, you will see these extra items in the 'Unused' section of the
-`gita info` output. To use them, edit `$XDG_CONFIG_HOME/gita/extra_repo_info.py`.
-
 ## Requirements
 
 Gita requires Python 3.6 or higher, due to the use of
 [f-string](https://www.python.org/dev/peps/pep-0498/)
 and [asyncio module](https://docs.python.org/3.6/library/asyncio.html).
 
-Under the hood, gita uses subprocess to run git commands/aliases.
+Under the hood, gita uses `subprocess` to run git commands/aliases.
 Thus the installed git version may matter.
 I have git `1.8.3.1`, `2.17.2`, and `2.20.1` on my machines, and
 their results agree.
@@ -243,18 +258,6 @@ A step-by-step guide to reproduce this project is [here](https://nosarthur.githu
 
 You can also sponsor me on [GitHub](https://github.com/sponsors/nosarthur). Any amount is appreciated!
 
-## Contributors
-
-[![nosarthur](https://github.com/nosarthur.png?size=40 "nosarthur")](https://github.com/nosarthur)
-[![mc0239](https://github.com/mc0239.png?size=40 "mc0239")](https://github.com/mc0239)
-[![dgrant](https://github.com/dgrant.png?size=40 "dgrant")](https://github.com/dgrant)
-[![samibh](https://github.com/github.png?size=40 "samibh")](https://github.com/samibh)
-[![wbrn](https://github.com/wbrn.png?size=40 "wbrn")](https://github.com/wbrn)
-[![TpOut](https://github.com/TpOut.png?size=40 "TpOut")](https://github.com/TpOut)
-[![PabloCastellano](https://github.com/PabloCastellano.png?size=40 "PabloCastellano")](https://github.com/PabloCastellano)
-[![cd3](https://github.com/cd3.png?size=40 "cd3")](https://github.com/cd3)
-[![Steve-Xyh](https://github.com/Steve-Xyh.png?size=40 "Steve-Xyh")](https://github.com/Steve-Xyh)
-
 ## Other multi-repo tools
 
 I haven't tried them but I heard good things about them.