Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
noeddl committed May 20, 2024
1 parent b5c8c36 commit 11255a5
Showing 1 changed file with 20 additions and 6 deletions.
26 changes: 20 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,22 @@

`ukebox` is a ukulele chord toolbox for the command line written in Rust.

## Table of contents

- [ukebox](#ukebox)
- [Table of contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Chord chart lookup](#chord-chart-lookup)
- [Chord name lookup](#chord-name-lookup)
- [Voice leading](#voice-leading)
- [Supported chord types](#supported-chord-types)
- [Development](#development)
- [Pre-commit hooks](#pre-commit-hooks)
- [License](#license)
- [Contribution](#contribution)

## Features

* shows you how to play a given chord on a ukulele by printing a **chord chart** in ASCII art
Expand Down Expand Up @@ -333,21 +349,19 @@ C added 4th - Cadd4

### Pre-commit hooks

To automatically enforce coding conventions (especially when it comes to formatting), Git hooks are a good way to simplify things. Pre-commit hooks are run before each commit and check for certain conditions or actively change the files to be committed (e.g. in our case by formatting the code using `rustfmt`). The folder `.githooks` contains such a pre-commit script. It runs the Rust linter `clippy` and automatically formats the code before committing it using `rustfmt`. Both these tools need to be installed and you have to tell Git that it should use the hooks in `.githooks`.
To automatically enforce coding conventions, Git hooks can simplify the process. Pre-commit hooks run before each commit, checking conditions or modifying files (e.g., using rustfmt to format code). The .githooks folder contains a pre-commit script that runs the Rust linter clippy and formats the code with rustfmt. You need to install these tools and configure Git to use the hooks in .githooks.

```
$ rustup component add clippy
$ rustup component add rustfmt
$ git config core.hooksPath .githooks
```

From now on, the hooks will be run every time you run `git commit`. If a problem is found, the commit process is aborted and a message is shown describing the found problem. If `clippy` is showing you warnings you have to manually resolve or ignore them (see below). Any changed files have to be added again with `git add`, then rerun `git commit`. Repeat until the hooks find no more errors and the commit is successfully executed.

If you disagree to one or more of `clippy's` hints, you can ignore certain lints either for a specific block (e.g. a function) by adding `#[allow(LINT_NAME)]` in front of the block or globally by adding `#![allow(LINT_NAME)]` somewhere in the code, preferably at the top of `lib.rs`.
Now, the hooks will run every time you commit. If a problem is found, the commit process is aborted with a message. Resolve clippy warnings manually, add changed files with git add, and rerun git commit until no errors remain.

In a similar fashion, you can prevent `rustfmt` from automatically formatting a certain block by adding `#[rustfmt::skip]` in front of it.
To ignore clippy lints for specific blocks, use #[allow(LINT_NAME)], or globally with #![allow(LINT_NAME)] at the top of lib.rs. Prevent rustfmt from formatting a block by adding #[rustfmt::skip].

If you for some reason want to bypass the pre-commit hooks for a certain commit, you can do so by adding the option `-n` to `git commit`.
To bypass pre-commit hooks for a commit, add the -n option to git commit.

## License

Expand Down

0 comments on commit 11255a5

Please sign in to comment.