CI GitHub Action status badge Spellcheck Action status badge Markdownlint Action status badge

The yak command line utility is still WIP and to be regarded as alpha software, most features are working but it not ready for first official release

NAME

App::Yak - Application to help with yak shaving for Git repositories etc.

SYNOPSIS

my $yak->new();
my $rv = $yak->process();

DESCRIPTION

The yak shaver can scan a directory for files, which can be classified as yaks in need of shaving. Meaning files which are maintained else where are often copy-pasted.

The file names can be configured in a central configuration file, like this:

$HOME/.config/yak/checksums.json

{
    "CONTRIBUTING.md": "15701b6b27e1d49ca6636f2695cfc49b6622c7152f74b14becc53850811db54f"
}

If a file is encountered, which matches the name, the checksum of the encountered file is calculated and is compared to the checksum listed in the central file.

The recommendation is to have the checksum in the central file, reflect the authoritative revision and hence you can overwrite the file in the directory you where inspecting.

Alternatively to specifying a checksum, you can specify a file URL:

{
    "MANIFEST.SKIP": "file://MANIFEST.SKIP"
}

The file pointed to has to be available in: $HOME/.config/yak/files

Then yak can calculate the checksum dynamically, based on the reference file and can based on invocation copy the reference file to the location of the evaluated file in the case where the two differ.

CHECKSUM DATA FILE EXAMPLE

This JSON file should be created as $HOME/.config/yak/checksums.json.

{
    "CODE_OF_CONDUCT.md": "https://gist.githubusercontent.com/jonasbn/dc331774eb67d067981902cadd3955ba/raw/b41de645c599be51e40a27e856333eeea261c12b/yaksums.json",
    "CONTRIBUTING.md": "file://CONTRIBUTING.md",
    "PULL_REQUEST_TEMPLATE.md": "91dabee84afd46f93894d1a266a773f3d46c2c0b1ae4813f0c7dba34df1dc260",
    "MANIFEST.SKIP": "file://MANIFEST.SKIP"
}

IGNORING CERTAIN DIRECTORIES, FILES AND FILENAME PATTERNS

yak supports the ability to ignore:

This is accomplished using an implementation based on .gitignore. To not intervene and to let git and yak work in harmony. The files used by yak are named .yakignore.

The mean that you can:

YAK IGNORE FILE EXAMPLE

.git
local

The above example specified the local directory created by Perl’s Carton. Another good candidate could be the .git folder.

Since yak is processing a directory structure recursively, specifying directories should speed up the processing. Specifying single files by name can be used to skip a file specified in the data source file temporarily.

INVOCATION

yak takes the following command line arguments:

Command line arguments override the configuration.

RETURN VALUES

Note that --about return as success with out processing any data apart from reading configuration and parsing command line arguments.

ENVIRONMENT

yak supports the following environment variables:

CLI Color Control

The order of precedence is as follows for CLI color control:

This aims to follow the proposed standard described in this article.

Color Control

The order of precedence is as follows for color control:

Do note this works for the single environment variables, the command line arguments work generally.

CONFIGURATION

$HOME/.config/yak/config.yml

yak can be configured using the following parameters:

Configuration can be overridden by command line arguments, see “INVOCATION”.

EXAMPLE CONFIGURATION

This YAML file should be created as $HOME/.config/yak/config.yml.

verbose: false
debug: false
skip_emoji: ✖️
failure_emoji: ❌
success_emoji: ✅
failure_color: yellow
yakignores:
- .git
- local

DATA SOURCE

There are 3 ways to provide checksum data to yak.

The default data source is described in the “DESCRIPTION”. As a an alternative a per project file can be specified in the designated repository/directory.

The file should be named: .yaksums.json

The contents follow the same format as the $HOME/.config/yak/checksums.json.

This JSON file should look as follows:

{
    "<filename>": "<sha256 checksum for the file specifed by the filename>"
}

An example:

{
    "CODE_OF_CONDUCT.md": "https://gist.githubusercontent.com/jonasbn/dc331774eb67d067981902cadd3955ba/raw/b41de645c599be51e40a27e856333eeea261c12b/yaksums.json",
    "CONTRIBUTING.md": "file://CONTRIBUTING.md",
    "PULL_REQUEST_TEMPLATE.md": "91dabee84afd46f93894d1a266a773f3d46c2c0b1ae4813f0c7dba34df1dc260",
    "MANIFEST.SKIP": "file://MANIFEST.SKIP"
}

If you want to have Yak help you checking for the presence of a file, specify the boolean true instead of a checksum.

{
    "ISSUE_TEMPLATE.md": true,
    "README.md": true
}

Or you can issue an error if a file is present, which should not be there, again using a boolean, but set to false.

{
    ".vstags": false
}

COLORS

Terminal colors are awesome, but also not as easy to work with. yak supports quite a few and relies on the implementation made available by Term::ANSIColor, more options and more information is available, so please consult the Term::ANSIColor documentation for more details.

The default colors should be available in most terminals. The color faint is not supported by all terminals, but looks truly awesome, please consult the Term::ANSIColor documentation for compatibility details.

USING DOCKER

An experimental Docker implementation has been included with the repository.

It can be built using the following statement:

$ docker build -t jonasbn/yak .

And then run as follows:

$ docker run --rm -it -v $PWD:/tmp jonasbn/yak

It will consume all the command line arguments (see “INVOCATION”).

The Docker image has the following command line arguments embedded:

Since the ability to read files outside the Docker container is limited to mounted directories.

The mount point is expected to be a directory containing the files to be checked against the checksum data structure. Please see the “LIMITATIONS” for details.

If you want to utilize the supported environment variables (see “ENVIRONMENT”) you have to do something along the lines of:

$ docker run --rm -it -v $PWD:/tmp --env CLICOLOR=$CLICOLOR jonasbn/yak

API

noemoji

process

read_checksums

read_config

read_environment

subprocess

REQUIREMENTS AND DEPENDENCIES

yak is specified to a minimum requirement of Perl 5.10, based on an analysis made using Perl::MinimumVersion, implementation syntax requires Perl 5.8.0, so yak could be made to work for 5.8.0.

LIMITATIONS

ISSUE REPORTING

If you experience any issues with yak report these via GitHub. Please read the issue reporting template.

DEVELOPMENT

If you want to contribute to yak please read the Contribution guidelines and follow the pull request guidelines.

CONTINUOUS INTEGRATION

The GitHub repository of perl-app-yak was renamed from yak. This broke the continuous integration setup with Travis CI. Therefore this has been disabled for now and instead an experimental CI based on GitHub Actions is used.

MOTIVATION

Much of what I do is yak shaving. For you who are not familiar with the term:

"[MIT AI Lab, after 2000: orig. probably from a Ren & Stimpy episode.]
Any seemingly pointless activity which is actually necessary to solve
a problem which solves a problem which, several levels of recursion
later, solves the real problem you're working on."

REF: The Jargon File

Used commonly for repetitive and boring work, required to reach a certain goal.

AUTHOR

COPYRIGHT

yak is (C) by Jonas Brømsø, (jonasbn) 2018-2022

Image used on the yak website is under copyright by Shane Aldendorff.

LICENSE

yak is released under the MIT License

REFERENCES