denis/gis
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update README

Browse source
This commit is contained in:
Denis Lehmann 2025-09-11 13:11:49 +02:00 • committed by Denis Lehmann
parent 79ab269fe6
commit 0b555a668d
1 changed files with 63 additions and 52 deletions
Download patch file Download diff file Expand all files Collapse all files

115
README.org
View file

@ -9,87 +9,98 @@ It was inspired by [[https://wiki.ros.org/wstool][wstool]], [[https://github.com
* Usage * Usage
#+begin_example #+begin_example
Usage: gis [OPTIONS] [COMMAND] Usage: gis [OPTIONS] [COMMAND]
Show a status summary of all Git repositories which are found recursively in Show a status summary of all Git repositories which are found recursively in
current work directory. The colon colon-separated environment variable current work directory. The colon colon-separated environment variable
$GIS_PATH or the '-p' argument can be used to modify the search path. $GIS_PATH or the '-p' argument can be used to modify the search path.
All 'fetch' and 'pull' operations are executed in parallel. The number of All 'fetch' and 'pull' operations are executed in parallel. The number of
background jobs can be limited with the environment variable $GIS_JOBS or the background jobs can be limited with the environment variable $GIS_JOBS or the
'-j' argument. '-j' argument.
COMMANDS COMMANDS
fetch Execute 'git fetch --prune --all' for all found repositories fetch Execute 'git fetch --prune --all' for all found repositories
pull Execute 'git pull --recurse-submodules' for all found repositories pull Execute 'git pull --recurse-submodules' for all found repositories
which are behind upstream, includes 'gis fetch' which are behind upstream, includes 'gis fetch'
OPTIONS OPTIONS
-j, --jobs N Limit 'fetch' and 'pull' commands to N parallel jobs -j, --jobs N Limit 'fetch' and 'pull' commands to N parallel jobs
-p, --path PATH Use PATH for searching Git repositories -p, --path PATH Use PATH for searching Git repositories
-h, --help Show this help message and exit -h, --help Show this help message and exit
#+end_example #+end_example
* Dependencies * Dependencies
- At least Bash =v4= - At least Bash =v4=
- BSD =column= - BSD =column=
- Git - Git
* Installation * Installation
** Manual ** Manual
Place the =gis= script in your =$PATH=. Place the =gis= script in your =$PATH=.
To use the autocompletion feature source the =gis_completion.bash= script. To use the autocompletion feature source the =gis_completion.bash= script.
On ZSH additionally the =compinit= and =bashcompinit= modules must be loaded before sourcing the completion script: *** ZSH
#+begin_src sh On ZSH additionally the =compinit= and =bashcompinit= modules must be loaded before sourcing the completion script:
autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit #+begin_src sh
#+end_src autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit
#+end_src
** Scripts ** Scripts
Installation scripts for Bash (=install.bash=) and ZSH (=install.zsh=) are provided which will link the two files to =~/.local/{bin/gis,share/bash-completion/completions/gis}= and add the corresponding entries to =~/.bashrc= or =~/.zshrc=. Installation scripts for Bash (=install.bash=) and ZSH (=install.zsh=) are provided which will link the two files from the current repository to =~/.local/{bin/gis,share/bash-completion/completions/gis}= and add the corresponding entries to =~/.bashrc= or =~/.zshrc=.
Further updates of /gis/ require just =git pull=. Further updates of /gis/ require just =git pull= in the /gis/ repository.
** Nix Flake ** Nix Flake
This repository is also a [[https://nixos.wiki/wiki/Flakes][Nix Flake]]. This repository is also a [[https://nixos.wiki/wiki/Flakes][Nix Flake]].
/gis/ is provided as package under =github:Deleh/gis#gis=. /gis/ is provided as package under =github:Deleh/gis#gis=.
* Configuration
The default behavior can be adjusted with the following environment variables:
| Variable | Description | Example Value |
|------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------|
| =GIS_PATH= | Colon seperated list of paths. If set, they will be used as default search paths instead of the current work directory. Can be overwritten with the =--path= argument. | =$HOME/git:$HOME/code= |
| =GIS_JOBS= | Limit for the number of parallel =fetch= and =pull= jobs. | =10= |
* Syntax * Syntax
** Status Keys ** Status Keys
#+begin_example #+begin_example
$ - Dirty stash $ - Dirty stash
? - Untracked files ? - Untracked files
! - Local changes ! - Local changes
+ - Staged changes + - Staged changes
- - File removed - - File removed
» - File renamed » - File renamed
= - Both modified = - Both modified
⇕ - Diverged from upstream ⇕ - Diverged from upstream
⇡ - Ahead upstream ⇡ - Ahead upstream
⇣ - Behind upstream ⇣ - Behind upstream
✗ - Upstream gone ✗ - Upstream gone
#+end_example #+end_example
** Branches ** Branches
Branches which don't have the same name as the =origin/HEAD= reference are highlighted in yellow. Branches which don't have the same name as the =origin/HEAD= reference are highlighted in yellow.
You can manually check on which branch you working tree is on by executing the following command: You can manually check on which branch you working tree is on by executing the following command:
: git symbolic-ref refs/remotes/origin/HEAD : git symbolic-ref refs/remotes/origin/HEAD
Note, that the reference gets only set when the repository is initially cloned and doesn't update with =git fetch=. Note, that the reference gets only set when the repository is initially cloned and doesn't update with =git fetch=.
It can be updated like this: It can be updated like this:
: git remote set-head origin -a : git remote set-head origin -a
Or set it manually to any branch with: Or set it manually to any branch with:
: git remote set-head origin <branch_name> : git remote set-head origin <branch_name>
The number of additional local branches which are neither checked out, nor the =origin/HEAD= branch, is appended at the end of the branch output, e.g. =(+8)=. The number of additional local branches which are neither checked out, nor the =origin/HEAD= branch, is appended at the end of the branch output, e.g. =(+8)=.