# Tag

A simple program to organize plain text files with tags.

## Installation

### With cargo

Just run `cargo install tag` to install `tag` for your system.

### From the AUR

Run `paru -S tag` to install `tag` with the AUR.

### As a binary

Simply head to the [releases](https://github.com/miampf/tag/releases) page and download the latest release for your system.

## Usage

To use tag you must add a taglist as the first line of your text files. A tagline looks like the following:

```
tags: [#tag1 #tag2]
```

The tags in the tagline start with a `#` followed by letters (some none-ASCII letters are also supported), numbers, `_` and `-`. This tagline **must** be the first line of your file and **must not** be larger than one line. You can find the tagline grammar under [tagline.pest](./tagline.pest).

Once you've added taglines to your local files you can run `tag`. `tag` will search all subdirectories of a given directory and check if tagged files match your search query.

The `tag` help message:

```
Search for local text files with a simple tagging system.

Usage: tag [OPTIONS] <PATH> [QUERY]

Arguments:
  <PATH>   The path that will be searched
  [QUERY]  Search query for the tags

Options:
  -s, --silent
          Only print the paths of matched files
  -c, --command <COMMAND>
          A command that will be executed on matched files
  -f, --filter-command <FILTER_COMMAND>
          A command that must run successfully for a file to be accepted
  -n, --no-color
          Disable coloring
  -q, --query-stdin
          Receive a query from the standard input
  -i, --inspect
          Enter an interactive inspection mode to view each file individually
  -h, --help
          Print help
  -V, --version
          Print version

```

A query contains operators and tags. Usable operators are `&` for the logical AND, `|` for the logical OR and `!` as a unary NOT. Furthermore, you can nest queries by using parantheses. A query could look like this:

```
#tag1 & #tag2 | (!#tag3 & #tag4)
```

This query would match all files that contain `#tag1` AND `#tag2` OR files that don't contain `#tag3` while also containing `#tag4`. You can find the query grammar under [query.pest](./query.pest).

### Commands

`tag` supports two flags that execute a system command. The `-c`/`--command` flag lets you add a command that should be executed on each matched file. The `-f`/`--filter-command` flag checks if an executed system command exits successfully. If not, the found file will not match, even tho it contains tags matching the query. You can use the string `#FILE#` in your command. This string will be replaced with the filepath of the file that matched the query. For example, the command

```
tag "#asdf" . -f "grep 'something' #FILE#" -c "echo 'somethingelse' >> #FILE#"
```

Will only match the files tagged with `#asdf` that also include the string "something". The string "somethingelse" will then be appended to each found file.

### Inspect mode

You can use the inspect mode using `-i`/`--inspect`. In this mode, the content of each file as well as the output of your `-c` command and found tags will be displayed. Keybindings are displayed at the bottom of the screen.

Furthermore, inspect mode supports executing further commands on your files. Those commands are formatted the same way as a command on a file or a filter command.