wrut

A utility to manage project templates.

Table of Contents

• Feature Overview
• Documentation
• Configuration
  • Default Configuration
• Command-Line Usage
• TODO

Feature Overview

• Project template creation and management.
• Project creation and management.
• Macro expansion when creating new projects from existing templates (WIP).
• Tags to better organize and filter templates and projects (WIP).

Command-Line Usage

You can run wrut --help to get the full help message.

You can also run wrut <TYPE> <COMMAND> --help to get more detailed information about a given command.

Documentation

Documentation for the wrut utility can be viewed at https://y-mx-b.github.io/wrut/.

TODO

• Template creation and management
• Project creation and management
• Split backend logic into a separate library
• Documentation
• Improve backend organization
• Tags (improve)
• Improve list output
• Snapshots (using git?)
• Develop internal template format
• Macros

Installing wrut

wrut can be installed through cargo:

cargo install wrut

You can also decide to build wrut from source. If so, simply clone the directory and run cargo build --release to build wrut.

git clone https://github.com/y-mx-b/wrut.git
cd wrut
cargo build --release
./target/release/wrut --help

Installation scripts are planned for the future, perhaps when wrut hits 1.0.

Setting up wrut

Before using wrut, you must first set up wrut's storage and configuration directories.

wrut --setup a

This command will set up wrut's storage directories at ~/.wrut and the configuration directory at ~/.config/wrut. For more information about wrut's internals, check the relevant documentation.

You can also use the --setup option to overwrite data/configuration directories:

wrut --setup t,p,c

This command would overwrite the template, project, and configuration directories to their defaults. Check wrut --help for more options.

Creating New Templates

Let's say your creative urges have struck and you have a sudden desire to write a novel. Being the scatterbrained yet technically savvy individual you are, you know very well that you're going to create, delete, and create ever so many writing projects, but you can't be bothered to set up your projects manually. Fear not, for wrut is here to help!

Let's create a new template to serve as the backbone for our writing projects. First, we'll create a new directory and add a couple files to it.

mkdir "Novel Template"
cd "Novel Template"
echo "# Title\nThis is my new novel!" >novel.md

Now, let's initialize this directory as a wrut project template.

wrut template init Novel

Alternatively, you could use the shorter aliases well.

wrut t i Novel

Now, if we run the list command, we can see that we've added a new template!

$ wrut t ls
Novel

Perfect!

Creating New Projects

Now, let's get to writing! First, let's create a new project directory.

cd ..
mkdir "My Novel"
cd "My Novel"
wrut project init Novel

We could provide wrut project init a project name as well, but if we don't, it'll simply use the name of the directory.

$ wrut p ls
My Novel

Now, we should have novel.md in this directory. Let's edit its contents!

<!-- novel.md -->

# My Novel 

This is my new novel!

Beautiful.

We can also use project new as an alternative to project init.

cd ..
wrut project new Novel "My Second Novel"

The new subcommand will create a new directory "My Second Novel" and then initialize it. It's no different from creating the directory and running project init, it's just quicker.

Managing Templates

You can view your templates with the template list command.

wrut template list

You can also use t ls for short.

wrut t ls

If you wish to delete a template, you can use the template remove command.

wrut template remove Novel

Now, if we run template list, we won't have any available templates.

$ wrut template list

However, the Novel Template subdirectory still exists. If we want to delete the directory as well, we can use the --delete flag.

wrut template remove Novel --delete

This will delete the template directory itself alongside the reference to it.

Managing Projects

We can also view our current projects with the list subcommand.

$ wrut project list
My Novel
My Second Novel

Naturally, the shortened version of the command will work as well.

$ wrut p ls
My Novel
My Second Novel

We can also use the remove subcommand to delete projects, and the --delete flag will also work, allowing us to delete references to projects as well as the project directory itself.

$ wrut project remove "My Novel"
$ wrut p rm "My Second Novel" --delete
$ wrut p ls

Macros

Creating New Tags

The new command allows you to create new tags.

wrut tag new <NAME> --templates <TEMPLATES> --projects <PROJECTS>

--templates and --projects are optional. Provided arguments for these flags, however, will add entries to their respective directories. Check Data Storage for more details.

Managing Tags

You can view all tags with the list command:

wrut tag list

Alternatively, you can inspect a single tag with the same command:

wrut tag list [NAME]

You can remove tags with the remove command:

wrut tag remove <NAME>

Global Configuration

wrut takes a --config argument, allowing you to specify the configuration file to use. By default, the configuration file is located at ~/.config/wrut/config.toml.

Default Configuration

[template]
ignore_dirs = []
ignore_files = []

[project]

Template Configuration

When you initialize or create a new template, a .wrut.toml is automatically created. It will have the same format as a global configuration, but is specific to the template. As such, it will automatically be loaded when you generate a project from said template.

Default Configuration

[template]
ignore_dirs = [
    '.git',
    'target',
    '.build',
]
ignore_files = ['.wrut.toml']

[project]

Data Storage

The data directory contains the templates, projects, tags, and .obj subdirectories. The .obj directory is used by wrut to store internal representations of templates for faster project generation. The other three are used to store data regarding templates, projects, and tags respectively.

The templates and projects directories contain symbolic links to actual template or project directories. The tags directory is a little more complex, in that it stores directories named after each tag, and each of these directories contains a templates and projects directory, which each contain an empty file named after the appropriate template/project.

Example ~/.wrut directory structure:

.wrut
├── projects
│   ├── Essay         # symlink; could point to ~/foo/bar, doesn't matter
│   └── wrut           # file name and real path are considered separately
├── tags
│   ├── Programming
│   │   ├── projects
│   │   │   └── wrut
│   │   └── templates
│   │       └── Rust
│   └── Writing
│       ├── projects
│       │   └── Essay
│       └── templates
│           └── LaTeX
└── templates
    ├── Rust          # symlink; same as with projects
    └── LaTeX