clink

A tool that helps developers keep track of changes that need to be made to files in response to other changes. Clink is agnostic to the programming language(s) used in your project, and allows you to put link directives in the comments of your source code to link to other parts of your codebase.

Using Clink

Tagging code to get reminders

Suppose you are planning on or in the process of doing a code refactoring. Your project may be using more than one programming language, involve documentation, etc. that you'd like to remember to change in response to changes to other parts of your code.

For example, you may have a couple of call sites like the following where you invoke an API client endpoint.

12. ...
13. // [clink tag](get_film_api)
14. let film = api_client.get_film_info(film_id)?;
15. ...

After we've added all of the tags we want to use, which mark places we'll want to receive reminders about, we can tell clink to scan our repository's contents to keep a record of these parts of our code.

clink setup

If there are directories or files you'd like to exclude, you can specify one or more using the -e or --exclude argument.

clink setup -e rust/target -e javascript/node_modules

Because clink is agnostic to the contents of your files, you can use it across programming languages as well.

This command creates a file called .clink in the root of your repository. This file contains a list of mappings tracking tags (such as get_film_api) and the files those tags are referenced in.

Specifying a section to watch for changes

Using the clink open and clink close directives, you can mark a section of code to be watched for changes by clink so that, when you modify the contents of the delimited lines of code, clink can tell you about tags inserted into related code, like in the example in the previous section.

Suppose the following code is where you have your implementation of the API client function used above.

// [clink open](get_film_api, to_refactor)
/// Fetches information about a requested film, given its ID in the API.
pub fn get_film_info(&self, film_id: ID) -> Result<Film, APIError> {
  ...
}
// [clink close]()

With this clink section in place, you can run clink after changing the get_film_info function body or signature but before using git add to stage the changes and clink will let you know about any other parts of the code tagged with either get_film_api or to_refactor.

clink

Building clink

Clink has been developed and tested with Rust 1.16 stable. However it should work fine with any version after and including 1.15 stable. If you don't already have the Rust compiler and cargo installed, you can get it from the official website. Once you've got it set up, you can build clink using the following commands.

# Grab the clink repository
git clone https://github.com/zsck/clink
cd clink
cargo build --release
sudo cp ./target/release/clink /usr/local/bin

You should now be able to get information about how to use clink:

clink help

Contributing

If you have suggestions for how to improve clink, please let me know by creating a Github issue! I'd love to receive help with improvements, and pull requests of any shape or size are very much welcome.