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
App::Yak - Application to help with yak shaving for Git repositories etc.
my $yak->new();
my $rv = $yak->process();
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.
- If they match, everything is okay
- If they differ, the difference has to be addressed
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.
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"
}
yak supports the ability to ignore:
- Files
- Directories
- Filename patterns
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:
- Specify patterns of files and directories in your configuration file, see "CONFIGURATION". This configuration will be overwritten if the next options are used.
- You can add an
.yakignorein the root of your repository and it will work for all files and directories in the file structure beneath it. Do note that the presence of this files, ignores and configuration in regard to using this feature. Meaning that disablingyakignores for a single repository can be accomplished by placing an empty.yakignorefile in the root of the repository. - a child
.yakignorecan be placed in a subsequent directory, working on all files and directories beneath it, do note that directories specified to be ignored in the parent.yakignoreare ignored and are not parsed and used.
.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.
yak takes the following command line arguments:
--verbose, enables more verbose output, can be configured see "CONFIGURATION"--silent, disables output and you have to rely on the return value see "RETURN VALUES" below.--debug, enables debug output. can be configured see "CONFIGURATION"--nodebug, disables debug output even if configured or provided as--debug, see above--config file, reads alternative configuration file instead of default, see "CONFIGURATION"--noconfig, disables reading of the configuration file, (see "CONFIGURATION") and you have to rely on the command line arguments--nochecksums, disables reading of the global checksums file, see "DATA SOURCE"--checksums file, reads alternative checksums file instead of default, see "DATA SOURCE"--color, enables colorized output, enabled by default or can be configured, see "CONFIGURATION"--nocolor, disables colorized output, even if configured or provided as--color, see above--emoji, enables emojis in output, enabled by default or can be configured, see "CONFIGURATION"--noemoji, disables emojis in output, even if configured or provided as--emoji, see above--about, emits output on configuration and invocation and terminates with success--help, emits help message listing all available options--version, emits version message listing version of the software
Command line arguments override the configuration.
0, success, everything is okay1, failure, a located filed did not match the designated checksum
Note that --about return as success with out processing any data apart from reading configuration and parsing command line arguments.
yak supports the following environment variables:
$CLICOLOR}, if set to false (0) it attempts to disable colorized output, if set to true (1), it attempts to enable colorized output$NO_COLOR, if set it attempts to disable colorized output, do note that value does not matter$CLICOLOR_FORCE, if set to true (1) it attempts to enable colorized output, if set to false (0), it attempts to disable colorized output$YAK_SUCCESS_COLOR, setting color for success messages, used when colors are enabled$YAK_FAILURE_COLOR, setting color for failure messages, used when colors are enabled$YAK_SKIP_COLOR, setting color for skip messages, used when colors are enabled$YAK_IGNORE_COLOR, setting color for ignore messages, used when colors are enabled
The order of precedence is as follows for CLI color control:
-
- Environment (this section),
$CLICOLOR_FORCE
- Environment (this section),
-
- Command line arguments,
--nocolorand--colorin that order, see "INVOCATION"
- Command line arguments,
-
- Environment (this section),
$NO_COLOR
- Environment (this section),
-
- Environment (this section),
$CLICOLOR
- Environment (this section),
-
- Configuration, see "CONFIGURATION",
colorconfiguration option
- Configuration, see "CONFIGURATION",
This aims to follow the proposed standard described in this article.
The order of precedence is as follows for color control:
-
- Command line arguments,
--nocolorand--colorin that order, see "INVOCATION"
- Command line arguments,
-
- Environment (this section),
$YAK_*_COLOR
- Environment (this section),
-
- Configuration, see "CONFIGURATION", colors configuration options:
success_color,failure_color,skip_colorandignore_color
- Configuration, see "CONFIGURATION", colors configuration options:
Do note this works for the single environment variables, the command line arguments work generally.
$HOME/.config/yak/config.yml
yak can be configured using the following parameters:
verbose, enabling (true) or disabling (false) more verbose outputdebug, enabling (true) or disabling (false) debug outputcolor, enabling (true) or disabling (false) colorized outputemoji, enabling (true) or disabling (false) colorized outputsuccess_emoji, setting emoji for success messages, used when emojis are enabledfailure_emoji, setting emoji for failure messages, used when emojis are enabledskip_emoji, setting emoji for skip messages, used when emojis are enabledignore_emoji, setting emoji for ignore messages, used when emojis are enabledsuccess_color, setting color for success messages, used when colors are enabledfailure_color, setting color for failure messages, used when colors are enabledskip_color, setting color for skip messages, used when colors are enabledignore_color, setting color for ignore messages, used when colors are enabledyakignores, specify a list of file directory names and patterns to be ignored
Configuration can be overridden by command line arguments, see "INVOCATION".
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
There are 3 ways to provide checksum data to yak.
- The default using:
$HOME/.config/yak/checksums.json, which can then be edited to match your needs - Using a project or repository specific:
.yaksums.jsonlocated in the root of your project or repository directory - Using an JSON file adhering to formatting described in this chapter, which can be located elsewhere on your file system
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
}
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.
blackred, default for failuregreen, default for successyellowblue, default for skip and ignoremagentacyanwhitebright_blackbright_redbright_greenbright_yellowbright_bluebright_magentabright_cyanbright_whitefaint
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.
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:
--noconfig--nochecksums
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
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.
- Clone
- Crypt::Digest::SHA256
- Data::Dumper
- Data::Stack
- Env
- File::Find
- File::Slurper
- Getopt::Long
- JSON
- List::MoreUtils
- LWP::UserAgent
- Term::ANSIColor
- Text::Gitignore
- version
- YAML::Tiny
yakis specified to a minimum requirement of Perl 5.10, based on an analysis made using Perl::MinimumVersion, implementation syntax requires Perl 5.8.0, soyakcould be made to work for 5.8.0.- Running under Docker is limited to using only checksums specified in a local <.yaksums.json> and configuration has to be specified using command line arguments not a file
- The use of a local:
.yaksums.jsonis limited to checksums and cannot calculate based on files, since files are located in an unmounted directory - The use of YAML implementation is based on YAML::Tiny and is therefor limited to this more simple implementation, which was however deemed sufficient for Yak.
yakdoes currently not support symbolic links when doing file system traversal. The implementation is based on File::Find and support for symbolic links could be enabled, but has not been regarded as necessary for now.- The parsing of
.yakignorefiles is based on Text::Gitignore and is limited to what this implementation supports, no known issues at this time.
If you experience any issues with yak report these via GitHub. Please read the issue reporting template.
If you want to contribute to yak please read the Contribution guidelines and follow the pull request guidelines.
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.
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.
- jonasbn, website
yak is (C) by Jonas Brømsø, (jonasbn) 2018-2022
Image used on the yak website is under copyright by Shane Aldendorff.
yak is released under the MIT License
-
- GitHub: "The Yak Project"
-
- MetaCPAN: TERM-ANSICOLOR
-
- Bixsense: "Standard for ANSI Colors in Terminals"
-
- NO_COLOR: "NO_COLOR"
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent