Elegant Git is an assistant who carefully automates routine work with Git.
Elegant Git is an assistant who carefully automates routine work with Git.
Please visit https://elegant-git.bees-hive.org/ to get started with user documentation or click on the picture :point_down::point_down::point_down: to see a demo.
:tada::tada::tada: That's all! :tada::tada::tada:
The information below guides you on different aspects of the development process. If you have something which should be quickly available, please propose changes here.
Table of contents
The structure of directories:
.
├── .workflows/ <- stores development scripts
├── bin/ <- stores executable which is entry point
├── completions/ <- stores completion files
├── docs/ <- stores user documentation
├── libexec/ <- contains all commands
├── tests/ <- stores all tests along with additional test libraries
└── workflows <- executes different development tasks
When you run git elegant ...
, it initiates bin/git-elegant
entry-point script. It calls
libexec/git-elegant
which is responsible for the execution of a given command by loading the code
of a desired command (using a command file like libexec/git-elegant-<command>
) and executing
it. Each command file has to provide the following BASH functions:
command-name
prints a command name (line length is limited to 50 characters)command-synopsis
prints a usage
statement (line length is limited to 80 characters)command-description
prints a command description (line length is limited to 80 characters)default
executes given commandThe following tools are needed for successful development:
We enforce having a consistent implementation by following the next strict rules:
#!/usr/bin/env bash
at the beginning of each scriptgit-verbose
or git-verbose-op
instead of git
command for well-formatted outputs--
If you need to write a message to the system output, please use public functions in
libexec/plugins/text. All help messages have to use cat
for printing them.
You can enable debug mode by running export GED=1
(the equivalent of set -x
for bash
).
Run unset GED
to switch debug off.
A testing procedure consists of 3 steps:
All these steps can be executed by ./workflows ci
which runs a Docker container (based on
beeshive/elegant-git-ci
image) and calls all described checks. The image is also used on CI.
If the image requires modifications, then
./workflows prepare-worker <new tag>
to build a new imageWORKER_IMAGE
in ./workflows
and test some workflow./workflows publich-worker <new tag>
to push the imageIn order to have a working unit tests, you need to add load addons-common
line to each .bats
file. This addon configures right access to executables (libexec
directory) and defines mandatory
functions.
Also, there are several optional addons which can be useful in some circumstances:
load addons-repo
to interact with real git repositoryload addons-fake
to fake a Linux commandload addons-cd
to fake cd
commandload addons-read
to fake read
commandsetup()
or teardown()
bats methods only in the tests.check
instead of bats run
to execute a command to be tested.perform-verbose
to execute any real command within a test which should not be tested.*-clean
function within a teardown()
method if the addon provides it.git-elegant
commands within the tests.[[ ${status} -eq 2 ]]
for a command status[[ ${#lines[@]} -eq 0 ]]
for a length of command output[[ ${lines[0]} = "+ the space " ]]
for an output line (index starts from 0)[[ ${lines[@]} =~ "exact string" ]]
for an output line within whole outputUse the following test name template - '<command>': <describes the behavior that will be tested>
like 'clone-repository': stops with exit code 45 if cloneable URL is not set
.
The behavior should be descriptive-style (stops with exit code 45 if cloneable URL is not set
)
rather than imperative-style (stop with exit code 45 if cloneable URL is not set
).
In order to get a preview of the documentation site locally, please run ./workflows serve-docs
and open http://localhost (happens automatically if you have open
command).
The docs/commands.md generates by running ./workflows generate-docs
script.
All other files in "docs" directory require manual corrections.
source completions/git-elegant.bash
source completions/_git-elegant
git-elegant <some>
and press Tab twiceWe use fourmolu as a formatting tool for haskell code. Fourmolu works in pipeline fashion. To reformat source code use:
$ git ls-files -z '*.hs' | xargs -0 fourmolu --mode inplace
To check if everything is formatted correctly, use:
$ fourmolu --mode check app src test