15 releases (6 stable)
|1.3.1||Jul 30, 2020|
|1.2.1||Nov 27, 2019|
|1.2.0||May 22, 2019|
|0.1.0||May 5, 2019|
|0.0.5||May 28, 2018|
#35 in Development tools
57 downloads per month
Tagref helps you refer to other locations in your codebase. For example, you might create a tag like this:
# This method always returns a non-empty list. [tag:wibble_nonempty] def wibble(x) ... end
Elsewhere, suppose you're writing some code which depends on that postcondition. You can make this clear by referencing the tag:
flobs = wibble(wobble) return flobs # This is safe due to [ref:wibble_nonempty].
Tagref ensures such references remain valid. If someone tries to delete or rename the tag (e.g., because they want to change what
wibble does), Tagref will complain. More precisely, it checks the following:
- References actually point to tags. A tag cannot be deleted without updating the references that point to it.
- Tags are distinct. There is never any ambiguity about which tag is being referenced.
By default, the syntax is
[tag:label] for tags and
[ref:label] for references. Tagref works with any programming language, and it respects your
.gitignore file as well as other common filter files. It's recommended to set up Tagref as an automated continuous integration check. Tagref is fast and probably won't be the bottleneck in your CI.
If you are running macOS or a GNU-based Linux on an x86-64 CPU, you can install Tagref with this command:
curl https://raw.githubusercontent.com/stepchowfun/tagref/master/install.sh -LSfs | sh
The same command can be used again to update Tagref to the latest version.
sh is dangerous since the server might be compromised. If you're concerned about this, you can download and inspect the installation script or choose one of the other installation methods.
The installation script supports the following environment variables:
VERSION=x.y.z(defaults to the latest version)
For example, the following will install Tagref into the working directory:
curl https://raw.githubusercontent.com/stepchowfun/tagref/master/install.sh -LSfs | PREFIX=. sh
If you have Cargo, you can install Tagref as follows:
cargo install tagref
You can run that command with
--force to update an existing installation.
The easiest way to use Tagref is to run the
tagref command with no arguments. It will scan the working directory and check the two conditions described above. Here are the supported command-line options:
USAGE: tagref [SUBCOMMAND] OPTIONS: -h, --help Prints help information -p, --path <PATH>... Adds the path of a directory to scan [default: .] -r, --ref-prefix <REF_PREFIX> Sets the prefix used for locating references [default: ref] -t, --tag-prefix <TAG_PREFIX> Sets the prefix used for locating tags [default: tag] -v, --version Prints version information SUBCOMMANDS: check Check all the tags and references (default) help Prints this message or the help of the given subcommand(s) list-refs List all the references list-tags List all the tags list-unused List the unreferenced tags