qk

qk allows you to quickly start new projects using templates

Usage

qk template project

Installation

Using cargo:

cargo install qk

Example

Consider the following config:

[templates.rs]
projects_dir = '/home/yourusername/projects/rs'
commands = ['cargo new $QK_PROJECT_NAME #{lib?}']
editor = 'vim'

The config is located in ~/.config/qk/qk.toml on Linux and in %appdata%\qk\config\qk.toml on Windows.

/home/yourusername/projects/rs/ will be created if it does not exist. On Windows it would be C:\Users\yourusername\projects\rs\.

$QK_PROJECT_NAME on Windows would be $Env:QK_PROJECT_NAME.

Now you can start a new rust project by typing qk rs myproject.

The command cargo new myproject will get executed in /home/yourusername/projects/rs, creating a new cargo package in /home/yourusername/projects/rs/myproject. Notice how $QK_PROJECT_NAME was replaced by myproject.

The commands are run with a shell, on windows it is PowerShell and on linux it is read from the environment variable $SHELL or if not set, the default is sh. So in windows you would use $Env:QK_PROJECT_NAME instead. You can also set the shell in the configuration file at the beginning of the file or in a specific template, as you would with the editor option.

These are the available environment variables:

• $QK_PROJECT_NAME the name of the project (myproject)
• $QK_PROJECT_DIR the directory of the project (/home/yourusername/projects/rs/myproject)
• $QK_PROJECTS_DIR the template's projects_dir (/home/yourusername/projects/rs)

After all the commands in the commands field are executed successfully, the command in the field editor will get executed with $QK_PROJECT_DIR as the argument, in this case opening vim in the directory of myproject.

The only required field is projects_dir, which is the directory where new projects will be located (i.e. where the commands will get executed). So you can also define a template like this:

[templates]
example = '/path/to/example'

# other templates...

And the only thing it will do is execute the editor in the project's dir.

See --editor help for information on what editor is used when not specified. You can set a default editor in the config by adding editor = 'your_editor' at the beginning of the config, for example:

editor = 'vim'

# your templates...

Next time you use qk rs myproject it will open the editor in the project's dir without executing any of the commands in the commands field.

And finally, there is another thing in the command that we haven't addressed yet: #{lib?}. This is a custom argument, lib is the name of the argument and ? means it is a flag; so if you use qk rs myproject -- --lib, the command executed will look like this: cargo new myproject --lib. The -- before the custom argument is required for arguments that start with -.

Custom arguments

Custom arguments can be specified with #{arg} in a command of a template in the config and, when calling qk, specified after -- (positional arguments don't need to be after --).

• A number followed by a colon at the beginning makes it a positional argument: #{1:arg}, #{2:arg2}, ...

• Just the name makes it an optional option: #{arg} (--arg value)

• Name followed by a comma and a single character adds a short version #{arg,a} (--arg value or -a value)

• Only comma followed by a single character disables long version #{,a} (-a value)

• * allows empty values: #{arg*} (--arg value or --arg ""), #{arg,a*}, #{,a*}, #{1:arg*} ...

• ! makes it required: #{arg!}, #{1:arg!}, #{arg,a!}, #{,a!}, #{arg!*}, #{arg,a*!}, #{,a!*}, ...

• ? makes it a flag: #{arg?} (--arg), #{arg,a?} (--arg or -a), #{,a?} (-a), ...

Example

~/.config/qk/qk.toml:

[templates.example]
projects_dir = '/path/to/example'
commands = ['echo hello #{1:name!} #{2:lastname} #{num} #{color,c}']

> qk example project
error: The following required arguments were not provided:
    <name>

USAGE:
     [OPTIONS] <name> [lastname]

For more information try --help
> qk example project john
$ echo hello john
hello john
> qk example project john -- --num 30
$ echo hello john  30
hello john 30
> qk example project john -- -c red
$ echo hello john   red
hello john red
> qk example project john -- -c red --num 10
$ echo hello john  10 red
hello john 10 red
> qk example3 project john -- -c red --num 10 doe
$ echo hello john doe 10 red
hello john doe 10 red
> qk example3 project -- --help


USAGE:
     [OPTIONS] <name> [lastname]

FLAGS:
    -h, --help    Prints help information

OPTIONS:
    -c, --color <color>
        --num <num>

ARGS:
    <name>
    <lastname>