---
**vGTD** is the Volt Package's task management tool. It is based on David
Allen's Getting Things DoneĀ® system.
Currently, vGTD only serves as a CLI
tool, usable in the terminal in command form. In the future, however, we plan
to add TUI and
GUI modes for the tool.
vGTD works within **workspaces**, which are files that hold arrays of lists and
other settings. **Lists** are containers that hold projects and tasks. A
**project** is a container that holds tasks. A **task** has a *name*,
*description*, and *status* and is used to describe a single actionable task.
### Creating a workspace
To start with, you need a workspace. A workspace is nothing but a file in the
local directory called `.gtd.toml`. In order to create it, use the `init`
command:
```bash
vgtd init # Create the workspace file with default contents
```
If your workspace is corrupted or you tried to create the file manually but
failed, use the `reset` command to reset a workspace:
```bash
vgtd reset # Reset the workspace file to the default contents
```
### Dealing with lists
Next, you can take a look at the currently available lists using the `lists`
command:
```bash
vgtd lists # Show the lists in the current workspace
```
This will show you the lists in the workspace, and the amount of tasks and
projects contained within them after their name.
You can create a list using `list create` and remove a list using `list
remove`:
```bash
vgtd list create "example" # Creates the list "example"
vgtd list remove "example" # Removes the list "example"
```
To see the contents of a list, use `list show`:
```bash
vgtd list show "example" # Show the contents of the list "example"
```
This will show the tasks and projects within the list. The projects will be
shown in a single line, with the amount of tasks held in them to the right of
their name. To see each project's tasks along with them, append the `--all`
option or its shortform `-a` to the end of `list show`:
```bash
vgtd lists show "example" --all # Show the projects' tasks as well
```
Right now, your lists are probably empty, so you'll see a "list is empty"
message instead.
### Item and container paths
vGTD wants its users to think of the location of projects and tasks like they
think of folders and files in their system. The names of projects and tasks are
often long and descriptive, so picking tasks and projects by their name in
order to use them in commands would prove to be a tiresome task. In order to
prevent this, indexes are used to refer to projects and tasks instead (hence
why you see indexes before project and task names when using `list show` and
`project show`). Indexes are currently one-based increasing numbers but will
work with an index-to-letter system that we plan to implement in the near
future.
All of that means that the path to the first task of the "inbox" list is
`inbox/1`, the second `inbox/2` and so on. Interestingly, the path to the first
*project* of the "inbox" list is *also* `inbox/1`. vGTD knows how to
differentiate one from the other by context, as it is often intuitive whether a
command wants a path to a task or to a task *container* (which can be a list or
a project). An example of a path to a task contained within a project is
`inbox/1/3`, that is, the task with index `3`, inside the project with index
`1`, inside the list `inbox`.
### Dealing with projects
It is often useful to organize yours tasks not only within lists, but also
within projects inside those lists. Not only that, but according to Mr. David
Allen, projects are often the *source* of many tasks. To create a project, use
`project create`, providing it with the name of the list to create the project
at and the name of the project:
```bash
vgtd project create "inbox" "test" # Create project "test" within the list "inbox"
```
You can see the contents of it using `project show`:
```bash
vgtd project show "inbox/1" # Show the contents of the first project within "inbox"
```
And if you ever want to get rid of a project, use `project remove`:
```bash
vgtd project remove "inbox/1" # Remove the first project within the "inbox" list
```
### Dealing with tasks
You now know how to deal with lists and projects and item paths, which is
great, but knowing how to manipulate task containers is useless if you don't
know how to deal with tasks, so here we go.
To create a task, use `task create`, providing the path to the container that
will hold the task and the name of the task to be created:
```bash
vgtd task create "inbox" "Implement the global workspace" # Create a task inside the "inbox" list
```
To remove a task you added by mistake or want to get rid of, use `task remove`
and provide the task's path:
```bash
vgtd task remove "inbox/1" # Remove the first task of the "inbox" list
```
To change the status of a task, use `task mark` and provide it with the task's
path. You can also provide it with the status to change the task to; by
default, vGTD assumes you want to mark it as "Done". Currently, tasks can only
be "Done" or "Todo", but in the future you'll be able to add your own statuses
or change the default ones.
```bash
vgtd task mark "inbox/1" # Mark the first task of the "inbox" list as done
```
### Moving things around
Now you can create, remove, and manipulate tasks, projects, and lists. Awesome!
But what if you create a task inside the wrong list? Do you have to remove it
and then create it again inside the right list? No! All you need to do is move
things around. To move a task from a task container to another, use `task move`
and provide it with the task's item path and the target task container's path
(yes, you can move tasks from projects to lists or from projects to projects in
other lists).
```bash
vgtd task move "inbox/1" "next" # Move the first task of the "inbox" list to the "next" list
```
You can move not only tasks, but entire projects as well! Using `project move`
you can move a project from a list to another:
```bash
vgtd project move "inbox/1" "next" # Move the first project of the "inbox" list to the "next" list
```
### Global mode
The initial and fundamental purpose of vGTD is to work with local repositories
of tasks, so you can control individual projects more easily. However, it is
often useful to be able to have a user-wide repository of tasks, so you can,
for instance, store your personal tasks and projects.
To address that necessity, vGTD has brought the **Global Workspace** feature to
2.0.
To access the Global Workspace from anywhere, just use any command like you
normally would, but add the `--global` option (or its shortform `-g`) after the
executable's name.
For instance, the command
```bash
vgtd task create inbox "Some personal task"
```
Becomes
```bash
vgtd --global task create inbox "Some personal task"
```
This won't create the task in the local workspace, but in the global one
(unless you are in the global workspace's directory, in which case they are the
same).
Location of the Global Workspace file
vGTD aims to be a cross-platform tool, and due to differences in the systems we
support, the Global Workspace file will be in a different place depending on
what OS you're using. This support comes from the `directories` crate, so the
following table is extracted directly from there (with the addition that we
appended the `.gtd.toml` file name to the end of the paths):
| Platform | Path |
|----------|------------------------------------|
| Linux | `$HOME/.gtd.toml` |
| macOS | `$HOME/.gtd.toml` |
| Windows | `{FOLDERID_Profile}/.gtd.toml`[^1] |
[^1]: This usually means `C:\Users\\.gtd.toml`.
### Getting help
If you forget the syntax of a command, want to know the meaning of an argument,
or discover which options are available to change the behavior of the command,
you can always use the `help` subcommand.
- `vgtd help` will summarize the major commands.
- `vgtd list help` will summarize the commands used to deal with lists.
- `vgtd task help` will summarize the commands used to deal with tasks.
- `vtd task create help` will provide information about the `task create`
command.
- And so on.