Git-Gamble

Blend TCR (test && commit || revert) + TDD (Test Driven Development) to make sure to develop the right thing, babystep by babystep

Original idea by Xavier Detant

- Theory - TCR - TDD - TCRDD - How to install - Requirements - Installation methods - AppImage - Debian - Mac OS X / Homebrew - Windows / Chocolatey - Nix / NixOS - Nix Flake - Project level - DirEnv - Home-Manager / user level - NixOS / system level - Cargo - Download the binary - Check the installation - How to use - Usage - Shells completions - When to use it ? - Backlog - Distribution / publishing backlog - Adding package to the X packages repository - CheckList - Technical improvement opportunities - Reinvent the wheel - Contributing - Development - Setup - Simple - Manual - Debug - Deployment

Theory

TCR

TCR (test && commit || revert) is cool! It encourages doing baby steps, reducing the waste when we are wrong

But it doesn't allow us to see the tests failing

So:

Maybe we test nothing (assert forgotten)

python def test_should_be_Buzz_given_5(): input = 5 actual = fizz_buzz(input) # Oops! Assert has been forgotten
Maybe we are testing something that is not the thing we should be testing

typescript it("should be Fizz given 3", () => { const input = 3; const actual = fizzBuzz(input); expect(input).toBe("Fizz"); // Oops! Asserts on the input value instead of the actual value });

TDD

TDD (Test Driven Development) is cool! It makes sure we develop the right thing, step by step

TCRDD

TCRDD = TCR + TDD

TCRDD blends the constraints of the two methods to benefit from their advantages

Therefore, TCRDD makes sure we develop the right thing, step by step, and we are encouraged to do so by baby steps, reducing the waste when we are wrong

```plantuml @startuml skinparam ArrowColor black

start repeat partition "red" #Coral { repeat :Write a test] :Gamble that the tests fail/ if (Actually run tests) then (Fail) -[#Red]-> :Commit; break else (Pass) -[#Green]-> :Revert; endif repeat while (Write another test) } partition "green" #Lime { repeat :Write the minimum code] :Gamble that the tests pass/ if (Actually run tests) then (Pass) -[#Green]-> :Commit; break else (Fail) -[#Red]-> :Revert; endif repeat while (Try something else) } partition "refactor" #668cff { repeat repeat :Write code without changing the behavior] :Gamble that the tests pass/ if (Actually run tests) then (Pass) -[#Green]-> :Commit; break else (Fail) -[#Tomato]-> :Revert; endif repeat while (Change something else) repeat while (Another things to refactor ?) } repeat while (Another feature to add ?) stop @enduml ```

If the above diagram is missing, you can see it on GitLab

git-gamble is a tool that helps to use the TCRDD method

How to install

Requirements

git-gamble doesn't repackage git, it uses the one installed on your system

You have to install git manually if you install git-gamble using :

AppImage
Debian
Cargo

Other installation methods include git as a dependency

Make sure it is available in your $PATH, you can check it with this command

shell git --help

Installation methods

AppImage

Download the latest version

shell curl --location "https://gitlab.com/api/v4/projects/pinage404%2Fgit-gamble/packages/generic/git-gamble-AppImage/2.4.0/git-gamble-v2.4.0-x86_64.AppImage" --output git-gamble-v2.4.0-x86_64.AppImage
Make it executable

shell chmod +x git-gamble-v2.4.0-x86_64.AppImage
Put it your $PATH

```shell

for example

mkdir -p ~/.local/bin ln git-gamble-v2.4.0-x86_64.AppImage ~/.local/bin/git-gamble export PATH+=":~/.local/bin" ```

Debian

Go to the package registry page
Go to the latest version of git-gamble-debian
Download the latest version git-gamble_2.4.0_amd64.deb
Install package

As root

shell dpkg --install git-gamble*.deb

This is not really convenient but a better way will come when GitLab Debian Package Manager MVC will be available

Mac OS X / Homebrew

Install Homebrew

shell brew tap pinage404/git-gamble https://gitlab.com/pinage404/git-gamble.git brew install --HEAD git-gamble

Windows / Chocolatey

Install Chocolatey

Go to the package registry page
Go to the latest version of git-gamble.portable
Download the latest version git-gamble.portable.2.4.0.nupkg
Install package

Follow GitLab's documentation and Chocolatey's documentation

shell choco install ./git-gamble.portable.2.4.0.nupkg

This is not really convenient, contributions are welcome

Nix / NixOS

Installation can be done at different levels, see below

It can be done with nix flake or with legacy way, in this case you will have to run command several times to change the sha256 and cargoSha256 by the given one by Nix

Nix Flake

Use without installing

bash nix run gitlab:pinage404/git-gamble -- --help

To install it, see usage example

Project level

In shell.nix

```nix { pkgs ? import {} }:

let git-gamble-derivation = pkgs.fetchurl { url = "https://gitlab.com/pinage404/git-gamble/-/raw/main/packaging/nix/git-gamble/default.nix?"; sha256 = "0000000000000000000000000000000000000000000000000000"; }; git-gamble = pkgs.callPackage git-gamble-derivation { version = "2.4.0"; sha256 = "1111111111111111111111111111111111111111111111111111"; cargoSha256 = "0000000000000000000000000000000000000000000000000000"; }; in pkgs.mkShell { buildInputs = [ git-gamble

# others dependencies here
pkgs.nodejs

]; } ```

Then run this command

shell nix-shell

DirEnv

To automate the setup of the environment it's recommanded to install DirEnv

Add in .envrc

direnv use nix

Then run this command

shell direnv allow

Home-Manager / user level

Install Home Manager

In ~/.config/nixpkgs/home.nix

```nix { pkgs, ... }:

# others dependencies here
pkgs.gitAndTools.git-absorb

]; } ```

Then run this command

shell home-manager switch

NixOS / system level

In /etc/nixos/configuration.nix

```nix { pkgs, ... }:

# others dependencies here
pkgs.bat

];

# This value determines the NixOS release with which your system is to be compatible, in order to avoid breaking some software such as database servers # You should change this only after NixOS release notes say you should system.stateVersion = "20.09"; } ```

Then run this command

shell nixos-rebuild switch

Cargo

Install Cargo

shell cargo install git-gamble

Add ~/.cargo/bin to your $PATH

Fish:

fish set --export --append PATH ~/.cargo/bin

Bash / ZSH:

bash export PATH=$PATH:~/.cargo/bin

Download the binary

Only for Linux and Windows x86_64

Download the binary on the release page
Put it in your $PATH

Check the installation

Check if all have been well settled

shell git gamble

If it has been well settled, it should output this :

```txt error: The following required arguments were not provided: ... <--pass|--fail>

USAGE: git-gamble --repository-path <--pass|--fail>

For more information try --help ```

If it has been badly settled, it should output this :

txt git : 'gamble' is not a git command. See 'git --help'.

How to use

To see all available flags and options

shell git-gamble --help # dash between `git` and `gamble` is only needed for --help

Write a failing test in your codebase, then :

shell git gamble --fail -- $YOUR_TEST_COMMAND
Write the minimum code to make tests pass, then :

shell git gamble --pass -- $YOUR_TEST_COMMAND
Refactor your code, then :

shell git gamble --pass -- $YOUR_TEST_COMMAND

It's a bit tedious to always repeat the test command

So you can set an environment variable with the test command to avoid repeating it all the time

shell export GAMBLE_TEST_COMMAND="sh -c 'cargo fix --allow-dirty ; cargo clippy --all-targets ; cargo check --all-targets ; cargo fmt ; cargo test'" git gamble --pass

Test command must exit with a 0 status when there are 0 failing tests, anything else is considered as a failure

Usage

git-gamble --help

``txt git-gamble 2.4.0 Blend TCR (test && commit || revert`) + TDD (Test Driven Development) to make sure to develop the right thing, babystep by babystep

USAGE: git-gamble [FLAGS] [OPTIONS] <--pass|--fail> [--] ... git-gamble [FLAGS] [OPTIONS]

FLAGS: -r, --fail Gamble that tests should fail [aliases: red] -g, --pass Gamble that tests should pass [aliases: green, refactor] -n, --dry-run Do not make any changes -e, --edit Open editor to edit commit's message -h, --help Prints help information --no-verify Do not run git hooks -V, --version Prints version information

OPTIONS: --fixup Fixes up commit -m, --message Commit's message [default: ] -C, --repository-path Repository path [default: .] --squash Construct a commit message for use with rebase --autosquash

ARGS: ... The command to execute to know the result [env: GAMBLETESTCOMMAND=]

SUBCOMMANDS: generate-shell-completions
help Prints this message or the help of the given subcommand(s)

Any contributions (feedback, bug report, merge request ...) are welcome https://gitlab.com/pinage404/git-gamble ```

Shells completions

To manually generate shell completions you can use this command

git gamble generate-shell-completions --help

```txt git-gamble-generate-shell-completions 2.4.0

USAGE: git-gamble generate-shell-completions

FLAGS: -h, --help
Prints help information

-V, --version    
        Prints version information

ARGS:
Put generated file here : * Fish https://fishshell.com/docs/current/completions.html#where-to-put-completions * Others shells ; Don't know, MR are welcome [possible values: zsh, bash, fish, powershell, elvish] ```

When to use it ?

You want to :
- learn nor practice TDD
- learn nor practice TCR without the drawbacks
- practice a new language
You follow the Test F.I.R.S.T. Principles

Backlog

when revert git clean
git workspace support
- git update-ref should contain an unique identifier to the workspace
- branche name ?
- folder path ?
gamble hooks
- branch based developement
- git commit --fixup
- git rebase --autosquash
- trunk based developement
- git pull
- git push
like git, flags & options & arguments should be retrieved from CLI or environment variable or config's file
- re-use git config to store in file ?
- repository level config using direnv and environment variable ?
stash instead of revert ?
shell completion
- in the package ?
- [ ] Cargo
- [ ] AppImage
- [ ] Chocolatey
- in sub command ?
for git gamble not only git-gamble

Distribution / publishing backlog

OS distribution
- Linux
- Nix
- RPM
  - cargo-rpm
- make AppImage updatable
  - bintray-zsync|pinage404|git-gamble-AppImages|git-gamble|git-gamble-_latestVersion-x86_64.AppImage.zsync
- SnapCraft ?
  - snapcraft's docs about rust
- FlatPak ?
- fpm : tool that help to generate to several packages
- document AppImage with firejail ?
- document AppImage with bubblewrap ?
- Open Build Service seems to be a service that build for every Linux targets
  - it can be use
  - thougth REST
    - badly documented
  - with ocs a CLI who seems to be a VCS like SVN (commit = commit + push)
    - who use the REST API under the hood
- Container Image (Docker) ?
- Awesome Rust Deployment
- Awesome Rust Platform Specific
URL to download latest version
- symlinks to URL containing the version name ?
- using GitLab Pages ?
versioned Homebrew Formula
- Use Cargo-Release to bump version
- how to update sha256 in the versioned file ?

Adding package to the X packages repository

Where the X packages repository is e.g. Nixpgks, Debian, Homebrew, Chocolatey ...

Feel free to do it, we don't plan to do it at the moment, it's too long to learn and understand how each of them works

If you do it, please file an issue or open an MR to update the documentation

CheckList

[ ] package in local
[ ] package in CI
[ ] upload
[ ] make public available
[ ] complete how to install
[ ] manual test
[ ] update backlog

Technical improvement opportunities

licence check
- cargo license
- cargo deny
smaller binary
- cargo bloat
- cargo deps

Reinvent the wheel

Why reinvent the wheel?

This script already works well

Because i would like to learn Rust ¯\_(ツ)_/¯

Contributing

Any contributions (feedback, bug report, merge request ...) are welcome

Respect the code of conduct

Follow Keep a Changelog

Development

Setup

To contribute with merge request

Simple

Install Direnv

Install Nix

Let direnv automagically set up the environment by executing the following command in the project directory

shell direnv allow

Manual

Rustup
clippy
rustfmt
rustfix
PlantUML if you want to see diagrams

Debug

There are some logs in the programs, pretty_env_logger is used to display them

There are 5 levels of logging (from the lightest to the most verbose) :

error
warn
info
debug
trace

The git-gamble logs are "hidden" behind the with_log feature

The option --features with_log (or --all-features) must be added to each cargo command for which you want to see logs (e.g.) :

sh cargo build --all-features cargo run --all-features cargo test --all-features

Then, to display logs, add this environment variable :

sh export RUST_LOG="git_gamble=debug"

To display really everything :

sh export RUST_LOG="trace"

There are other possibilities for logging in the env_logger documentation

Deployment

Just run cargo release (in a wide terminal, in order to have --help not truncated in the usage section)

sh cargo release

Git-Gamble

Theory

TCR

TDD

TCRDD

How to install

Requirements

Installation methods

AppImage

for example

Debian

Mac OS X / Homebrew

Windows / Chocolatey

Nix / NixOS

Nix Flake

Project level

DirEnv

Home-Manager / user level

NixOS / system level

Cargo

Download the binary

Check the installation

How to use

Usage

Shells completions

When to use it ?

Backlog

Distribution / publishing backlog

Adding package to the X packages repository

CheckList

Technical improvement opportunities

Reinvent the wheel

Contributing

Development

Setup

Simple

Manual

Debug

Deployment