--- **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.