Elegant 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 orclick on the picture �� �� �� to see a demo.

The contribution process at a glance

1. Everyone contributing is governed by the Code of Conduct - please read it
2. After, please get familiar with project rules described in CONTRIBUTING.md.
3. Make a contribution

�� �� �� That's all! �� �� ��

Hands-on development notes

The information below guides you on different aspects of the development process. If you havesomething which should be quickly available, please propose changes here.

Table of contents

• Architecture
• Development environment
• Coding rules
• Debug mode
• Testing procedure
• Unit testing
  • Addons
  • Writing tests
  • Assertions
  • Test name template
• Updating documentation

Architecture

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 callslibexec/git-elegant which is responsible for the execution of a given command by loading the codeof a desired command (using a command file like libexec/git-elegant-<command>) and executingit. 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 command

Development environment

The following tools are needed for successful development:

• Docker >= 19.03.2 is used for running tests
• Elegant Git is used for running the testing process and generating documentation

Coding rules

We enforce having a consistent implementation by following the next strict rules:

• add #!/usr/bin/env bash at the beginning of each script
• use whether git-verbose or git-verbose-op instead of git command for well-formatted outputs
• a private function (a usage in the scope of current script) should be prefixed with --

If you need to write a message to the system output, please use public functions inlibexec/plugins/text. All help messages have to use catfor printing them.

Debug mode

You can enable debug mode by running export GED=1 (the equivalent of set -x for bash).Run unset GED to switch debug off.

Testing procedure

A testing procedure consists of 3 steps:

1. unit testing using bats-core
2. installation testing
3. validation of documentation correctness

All these steps can be executed by ./workflows ci which runs a Docker container (based onbeeshive/elegant-git-ci image) and calls all described checks. The image is also used on CI.If the image requires modifications, then

1. run ./workflows prepare-worker <new tag> to build a new image
2. update WORKER_IMAGE in ./workflows and test some workflow
3. run ./workflows publich-worker <new tag> to push the image

Unit testing

Addons

In order to have a working unit tests, you need to add load addons-common line to each .batsfile. This addon configures right access to executables (libexec directory) and defines mandatoryfunctions.

Also, there are several optional addons which can be useful in some circumstances:

• add load addons-repo to interact with real git repository
• add load addons-fake to fake a Linux command
• add load addons-cd to fake cd command
• add load addons-read to fake read command

Writing tests

1. Use setup() or teardown() bats methods only in the tests.
2. Use check instead of bats run to execute a command to be tested.
3. Use perform-verbose to execute any real command within a test which should not be tested.
4. Use appropriate *-clean function within a teardown() method if the addon provides it.
5. Do not fake git-elegant commands within the tests.

Assertions

• [[ ${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 output

Test name template

Use 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).

Updating documentation

In order to get a preview of the documentation site locally, please run ./workflows serve-docsand 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.

Completions testing

1. source updated competion file
   • bash: source completions/git-elegant.bash
   • zsh: source completions/_git-elegant
2. run git-elegant <some> and press Tab twice