A POSIX compatible script to extract some informations about a git repository.
God Bless Git (GBG) is a shell tool which can extract repository informations in a simple and readable format. Thus, you can know:
- Repository informations: is the folder a git repository, which is the top folder, etc.
- Head informations: is head detached, head hash, branch, tag
- Workspace informations: are there and how many modified/deleted/untracked/ignored files
- Index informations: are there and how many added/modified/moved/deleted files
- Remote informations: is upstream declared, how many commits differ, etc.
This list will grow with time. Priorities goes to:
- Merge type: merge or rebase
- Current action: merge, rebase, bissect, etc.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
God Bless Git as few prerequisites.
First one is git which is required (in a version greater or equal than 2.13.0). You can install it with your distribution package manager (apt, yum, pacman, etc.) or compile it yourself (look git website).
Then, GBG rely on POSIX compliant system utilities as sed
, grep
, cut
, etc.
These should be already install on most of the POSIX systems.
If not, then you probably have a very custom system and so must be skilled enough to install them.
WARNING: Busybox's version of utilities have weird options/syntax and are very likely to not work properly with GBG.
There is some optional dependencies. On the one side, for code linting. We rely on ShellCheck and Bashate to warn us about the coding style. Just check their respective pages to know how to install them (nothing really complicated). On the other side, for testing. Here we rely on shUnit2. Hopefully, it is automatically installed the first time you run the tests, and so you do not have to install it manually.
God Bless Git does not need to be installed.
First, clone the repository:
git clone https://github.com/AlexisBRENON/god-bless-git.git
That's it, GBG is ready to use. See deployment to know how to use it in real life.
Some tests are distributed alongside the source code. While, one day, they will be executed on a continuous integration server, you can still run them locally.
These ones test that Gob Bless Git behave as expected, i.e. that the right variables are defined correctly. You can run all of them using the following command:
make functionnal-tests
You can also run only one with:
make tests/functionnal/<test_type>_test.sh
GBG also comes with a profiling test, checking that execution time is not excessive. You can execute it with:
make profile
As explained in the prerequisites part, we rely on ShellCheck and Bashate to lint the code. You can run these both linting checkers on the whole code base with the following command:
make lint
It exists two ways to use God Bless Git:
This way of using GBG is probably the best way if you intent to often fetch Git informations. It is also the way GBG has been designed.
First, source one of the init script (note the '.
' at the line start):
. god-bless-git/god_bless_git.sh
Or, for ZSH user
. god-bless-git/god_bless_git.plugin.zsh
Note: Depending on your shell (in particular, on classical sh
), init script is not able to determine GBG root directory.
It is possible to overcome this providing the path of this directory in the GBG_DIR
environment variable.
You now have a god_bless_git
function declared which will populate GBG's variables each time you call it.
For example, move to a non git repository folder (like /tmp
) and run:
cd /tmp
god_bless_git
At this point GBG's variables have been added to your environment. You can print the list of these variables with the following command:
set | grep -aE '^gbg_'
Here is the sample output:
gbg_head_branch=''
...
gbg_is_a_git_repo=false
...
gbg_workspace_untracked_num=''
Then move back to the god_bless_git
folder and run again the previous commands:
cd god_bless_git
god_bless_git
set | grep -aE '^gbg_'
The GBG's variables have been updated, and here is an example output (which can be different from yours):
gbg_head_branch=master
...
gbg_is_a_git_repo=true
...
gbg_workspace_untracked_num=1
The complete list of variables populated can be found on the dedicated documentation page. This list of variables can also be acquired by invoking the script directly.
If you want to get Git informations just once, you can invoke GBG as any other standard commands.
Execute the init script from your shell:
./god-bless-git/god_bless_git.sh
Even better, if the god-bless-git
appears in your PATH variable (or you linked the init script in any PATH registered folder), you can just call the script without any prefix:
god_bless_git.sh
This will display the list of GBG's variables, that is to say all the lines starting with gbg_
in the set
command output, as presented in the sourcing examples.
- ShellCheck, a static analysis tool for shell scripts.
- Bashate - Code style enforcement for bash programs.
- shUnit2, a xUnit based unit test framework for Bourne based shell scripts.
- README-Template.md, a template to make good
README.md
.
Anybody is very welcome to contribute in any manner: asking features, reporting bugs, making pull requests, etc. There is no particular contribution guidelines, just be clear and kind.
We use SemVer for versioning. For the versions available, see the tags on this repository.
- Alexis BRENON - Initial work
This project is licensed under the MIT License - see the LICENSE.md file for details
- oh-my-git which gives me the inspiration and a great code base as a starting point.