wutag 🔱🏷️

master A command line tool for colorfully tagging files

NOTE: This program uses the nightly compiler for the feature adt_const_params, which allows using const parameters in functions.

Todo

Flags

These flags apply to mostly all all commands. If the command involves a pattern, then all flags will apply. Also, see --help for the main binary or any subcommand for longer explanations of most options.

OPTIONS:
    -v, --verbose              Display debugging messages on 4 levels (i.e., -vv..)
    -d, --dir <dir>            Specify starting path for filesystem traversal
    -m, --max-depth <num>      Increase maximum recursion depth from 2
    -R, --registry <reg>       Specify a different registry to use
    -i, --case_insensitive     Case insensitively search
    -s, --case_sensitive       Case sensitively search
    -r, --regex                Search with a regular expressions
    -g, --global               Apply operation to all tags and files instead of locally
    -l, --ls-colors            Respect 'LS_COLORS' environment variable when coloring the output
    -c, --color <when>         When to colorize output
    -t, --type <filetype>      File-type(s) to filter by: f|file, d|directory, l|symlink, e|empty
    -e, --ext <extension>      Filter results by file extension
    -E, --exclude <pattern>    Exclude results that match pattern
    -h, --help                 Print help information
    -V, --version              Print version information

Subcommands

list Lists all available tags or files set Set tag(s) on files that match the given pattern rm Remove tag(s) from the files that match the provided pattern clear Clears all tags of the files that match the provided pattern search Searches for files that have all of the provided 'tags' cp Copies tags from the specified file to files that match a pattern view View the results in an editor (optional pattern) edit Edits a tag's color clean-cache Clean the cached tag registry print-completions Prints completions for the specified shell to directory or stdout

list

FLAGS:
    -r, --raw        If provided output will be raw so that it can be easily piped to other commands
    -h, --help       Print help information
    -v, --verbose    Display debugging messages on 4 levels (i.e., -vv..)

SUBCOMMANDS:
    tags
    files

list files

Note: list tags only has notable option, which is --border.

FLAGS:
    -h, --help         Print help information
    -t, --with-tags    Display tags along with the files
    -f, --format       Format the tags and files output into columns
    -b, --border       Use border separators when formatting output
    -v, --verbose      Display debugging messages on 4 levels (i.e., -vv..)
    -G, --garrulous    Display tags and files on separate lines

Examples

wutag -g list files -t   # List all files with tags
wutag list files -tfb    # List files in cwd with formatted tags + borders
wutag list files -tfb    # List files in cwd with formatted tags + borders
wutag -g list tags -b    # List all tags with borders

set

USAGE:
    wutag [FLAG/OPTIONS] set [FLAG/OPTIONS] <pattern> <tag>

ARGS:
    <PATTERN>    A glob pattern like "*.png"
    <TAGS>...

FLAGS:
    -q, --quiet      Do not show errors that tag already exists
    -c, --clear      Clear all tags before setting them
    -h, --help       Print help information
    -v, --verbose    Display debugging messages on 4 levels (i.e., -vv..)

OPTIONS:
    -C, --color <COLOR>    Explicitly select color for tag

Examples

wutag -E src/ -e rs -e go set '*' <tag>       # Exclude src/ & set all files with 'rs' or 'go' extension to <tag>
wutag -E src/ set '*{rs,go}' <tag>            # Tag all 'rs' and 'go' files
wutag -E src/ -r set '.*\.(rs|go)' <tag>      # Same as above except as a regular expression
wutag -i set '*glob' <tag> --color="#EF1D55"  # Ignore case and set specific color
wutag -d ~/dir set '*glob' <tag>              # Set tag in another directory
wutag -R ~/dir/new.reg -td set '*glob' <tag>  # Set tag in another registry on directories
wutag set --clear '*glob' <tag>               # Clear the tags before setting the new ones

rm

Has no special options. All main binary options apply.

clear

Clears all tags from files matching globs. This can also be used to clear tags from files that are still in the registry but are no longer on the file-system, but using the command wutag clear --non-existent

Differences with my fork and the original

New directory locations

Global option

Display and formatting

Searching

Multiple registries

`WUTAG_REGISTRY="$XDG_CONFIG_HOME/wutag/my.registry wutag set '*.rs' rust"`

Deleted files

Default command

Aliases and subcommand inferencing

New command similar to what add vs set would be

Completions

Color

File execution

# {@c}
wutag -g search '*.txt' -t xx -x {@c} '*.toml'

Edit tags in $EDITOR

wutag view --all -p <pattern> # view *all* files matching pattern
wutag view                    # view all files that are already tagged
wutag view -a -f json         # view all files that are already tagged in json format

Set tags through stdin

fd -e rs '*main*' | wutag set --stdin tag1 tag2
# Note that --stdin does not need to be explicitly called
fd -e rs '*main*' | wutag set tag1 tag2

Example usage

Install

If you use arch Linux and have AUR repositories set up you can use your favorite AUR manager to download wutag. For example with paru:

If you're on another Linux distribution or macOS you can download one of the pre-built binaries from here.

To build manually you'll need latest rust and cargo. Build with:

Usage

By default each tag will be assigned with a random color from 8 base colors (either bright or normal so 16 colors in total). You can later edit each tag by using edit subcommand like this:

Each command that takes a pattern starts a filesystem traversal from current working directory. To override this behaviour specify a global parameter --dir or -d like this:

Default recursion depth is set to 2. To increase it use --max-depth or -m global parameter.

After tagging your files with set like:

To utilize the list by other programs pass the --raw or -r flag to search subcommand like:

When --any flag is provided as in the example wutag will match files containing any of the provided tags rather than all of them.

If you are into emojis then surely you can use emojis to tag files 🙂 wutag set '*.doc' 📋

Configuration

wutag lets you configure base colors used when creating tags or modify other settings globally. There will be a wutag.yml file located in $XDG_CONFIG_HOME/wutag or $HOME/.config/wutag with only max_depth in it. Colors can be added like so:

Example configuration:

---
base_color: "#FF5813"       # default color of file path
border_color: "#A06469"     # default color when using `list files -tfb`
format: "yaml"              # default command when viewing tags in editor
max_depth: 100              # maximum depth to recurse when applying function to files
colors:                     # list of colors to choose from when setting tags
    - '0xabba0f'            # can be in formats other than #RRGGBB
    - '#121212'
    - '0x111111'
ignores:                    # list of paths to always ignore
    - "src/"
    - "Library/"
    - "**/foo/bar"

Tab completion

To get tab completion use wutag print-completions --shell <shell> > /path/to/completions/dir/... to enable it in your favorite shell.

Available shells are:

To enable completions on the fly use:

User interface

Usage

USAGE:
    wutag [FLAGS/OPTIONS] <SUBCOMMAND> [TAGS/FLAGS]

FLAGS:
    -h, --help                Print help information
    -V, --version             Print version information
    -i, --case-insensitive    Case insensitively search
    -r, --regex               Case insensitively search
    -g, --global              Apply operation to all tags and files instead of locally
    -l, --ls-colors           Respect 'LS_COLORS' environment variable when coloring the output
    -v, --verbose             Display debugging messages on 4 levels (i.e., -vv..)

OPTIONS:
    -d, --dir <DIR>...            Specify starting path for filesystem traversal
    -m, --max-depth <num>         Increase maximum recursion depth from 2
    -R, --registry <REG>          Specify a different registry to use
    -c, --color <when>            When to colorize output
    -e, --ext <extension>...      Filter results by file extension
    -E, --exclude <pattern>...    Exclude results that match pattern

SUBCOMMANDS:
    list                 Lists all available tags or files
    set                  Set tag(s) on files that match the given pattern
    rm                   Remove tag(s) from the files that match the provided pattern
    clear                Clears all tags of the files that match the provided pattern
    search               Searches for files that have all of the provided 'tags'
    cp                   Copies tags from the specified file to files that match a pattern
    edit                 Edits a tag
    clean-cache          Clean the cached tag registry
    print-completions    Prints completions for the specified shell to stdout

See wutag --help for longer explanations of some base options.
Use --help after a subcommand for explanations of more options.

More help

Use the --help flag for longer explanations on some flags, as well as --help|-h after each subcommand to see the available options. Tip: If completions are installed it will help a ton.

Credit

License

MIT