path: root/README.mdown

vgstash is a tool used to keep track of a video game collection. In addition to
basic inventory maintenance, vgstash supports the ability to clarify whether or
not the user owns a game, and their progress through said game. This makes it
easy to manage a backlog and serve as a "memory" for which games someone has
finished.

# Concept

Essentially, vgstash just gets out of your way and lets you manage things.
Nothing fancy like box art or finding games in a massive dropdown box. There are
easy flags to track common searches, like "All games that are owned and haven't
been beaten", making vgstash convenient.

Since vgstash itself is just a front-end to an SQLite database, other
interfaces to this basic database format can be built to extend the basic
concept. SQLite is supported across tons of languages and platforms, so it's
rather trivial to build another frontend to it. If that's not enough, vgstash 
also supports exporting collections as YAML or pipe-delimited lines, and 
importing from YAML. This makes batch-editing by a human easy with YAML, and the 
raw format is great for pushing vgstash's output through pipes, as any good 
\*nix tool should.

## Data Format

The key to managing things is keeping it simple, but flexible enough to give you
meaningful insight to the data itself. vgstash gets straight to business
with its data format:

* Name (string)
* System (string)
* Ownership (boolean)
* Completion Level (integer)
    * 0 (Fresh)
    * 1 (In Progress)
    * 2 (Beaten)
    * 3 (Completed)

There isn't a hard limit on the length of the Name or System strings. SQLite 
itself, however, has internal limits. Those limits may differ between platforms, 
so there's no guarantee that vgstash databases will work across them. The 
`import` and `export` functions should be used to transport vgstash databases 
from one platform to another, as YAML is better-standardized and easily 
modifiable.

# Usage

Using vgstash is fairly easy, for a command-line program. It accepts
a handful of commands, which will be explained below:

* init
* add
* update
* delete
* list
* import
* export

## Tips

For the sake of accessibility and ease of use, there are some synonyms:

When specifying ownership, `0` (zero) and `n` mean the same thing. The same is
true of `1` (one) and `y`.

When specifying progress, the numbers and letters can both be used:

`0` is also `f` or "fresh".  
`1` is also `i` (lowercase I) or "in-progress".  
`2` is also `b` (lowercase B) or "beaten".  
`3` is also `c` (lowercase C) or "completed".

Since vgstash relies on the shell and SQLite to function, unquoted strings 
are likely to not be handled well. If your data ever looks funky, try correcting 
it with a quoted string. Bugs or issues that are reported without quoted strings 
will be discarded as WONTFIX, as that's basic, sane practice in every shell 
under the sun.

## Getting Started

Initialize the database, where your information will be stored:

~~~
vgstash init
~~~

The location of the database may be set using an environment variable. To learn 
more, see the Environment Variables section.

## Adding

Next, add a game or two:

~~~
vgstash add "Super Mario Bros" NES y i
~~~

In the above example, we're adding *Super Mario Bros* for the NES system. We own 
it, and haven't beaten it yet.

Let's add another:

~~~
vgstash add "Borderlands 2" PC
~~~

This command has just the basics: game name, and game platform. For the sake
of simplicity, the ownership and progress flags have default values: ownership
defaults to "y" for "yes" and progress defaults to "i" for "in-progress". In
both cases, they are the most typical state for a video game to be added to ones
collection. This can be influenced; see the Environment Variables section for
more info.

## Listing

vgstash has plenty of methods to interface with your game collection. The 
simplest listing would be "list every game in the database":

~~~
# The 'all' is optional
vgstash list all
~~~

This will output a human-readable list of games you have in the database, with
proper flags and unique IDs, which will come in handy later. For ease of use,
`list all` will sort by system, then by title. Here's an example:

~~~
ID | Title               | System | Own | Progress
---+---------------------+--------+-----+----------
3  | Metroid             | NES    | *   |   I
1  | Super Mario Bros    | NES    |     |       C
2  | The Legend of Zelda | NES    | *   |     B
4  | Borderlands         | PC     | *   | F
~~~

From the above output, we can gather that we don't own *Super Mario Bros* 
anymore. It's been completed, however, so that's good news. We own *Zelda*, and 
it's been beaten, but not completed. We also own *Metroid*, but it's still 
in-progress. Lastly, we own Borderlands for the PC, but haven't started playing 
it yet.

The output format is designed to be easy to read, and omits information to serve
as a visual guide whenever possible. From a single glance, you should be able to
spot which games you own and which haven't been started yet.

### List Filtering

Seeing all of your games is great when you're just getting started, but what 
about after you've added your massive 500 game collection? Nobody wants to sort 
through screenfulls of text. That's where filtering comes in. The `list` command 
accepts the following filters:

* **completed**  
    List games that have been completed.

* **done**  
List games that have been beaten *or* completed.

* **owned**  
List games that you own.

* **unowned**  
List games that you don't own.

* **wishlist**  
List games that you don't own AND are fresh.

* **incomplete**  
List games that have been beaten, but not completed, that you also own.

* **backlog**  
List games that have not been beaten or completed, that you also own.

## Update

The `update` command requires the game's ID, the field you're changing, and the 
value you're changing it to.

The fields you can change are

* title
* system
* ownership
* progress

As explained in **Data Format**, ownership and progress can use single letters 
to substitute for the internal numeric representations.

To get a game's ID, try using something like `vgstash list | grep "foo"` to find
what you're looking for.

## Deleting

For one reason or another, you may need to remove items from your game database.
The `delete` command, coupled with the game's ID, will take care of that for
you. If you want to remove *every* game from your collection, delete the
`.vgstash.db` file from your $HOME directory (or whatever `VGSTASH_DB_LOCATION`
is set to) and start over with `vgstash init`.

# Environment Variables

Customization is pretty important if you're going to manage hundreds of games. 
There are only a few, but they may come in handy for you!

* `VGSTASH_DB_LOCATION`  
    Defaults to `$HOME`. A file named `.vgstash.db` will be found there.

* `VGSTASH_DEFAULT_OWNERSHIP`  
    Can be 0 or 1. Default is 1 (yes).

* `VGSTASH_DEFAULT_PROGRESS`  
    Can be 0 through 3. Default is 1 (in-progress).

* `VGSTASH_TABLE_WIDTH`  
    The width of the table output by the `list` command. For readability 
reasons, vgstash will only allow values that are 50 or above. If this variable 
is set to zero (0) however, it will expand to fit the entire width of your 
terminal/tty. It defaults to 80 characters.

# Contributing

vgstash was first written in Python 3.4. There are no plans to produce a Python 
2.x version. Patches and pull requests are welcome! However, please do not 
contribute to this project unless you are fine with your contributions also 
being licensed under the GPL 3.0. This is to simplify licensing issues and keep 
things neat.

Before submitting a Pull Request, please ensure that your commit(s) contain
an addition of your name to the `AUTHORS` file. Others may not use GitHub (or
even git) to get or use vgstash, and every contributor deserves recognition. An
example of what one would add to the `AUTHORS` file is:

~~~
John Q. Public, GitHub: @hellomynameisjohn <jqp@genericville.com>
    Corrected typos in manpage
~~~

Note that the indent is four spaces.

# Roadmap

vgstash is considered beta-quality at this time. Please report any issues, bugs, 
or even suggestions on how to improve vgstash.

One feature that will not be built (at least by zlg) is search functionality. 
Since vgstash cooperates with piping, it's trivial to pass its output through 
other programs and get the fine-grained information a more advanced user may 
need.

Here are the current goals:

* manpage
* bash-completion file
* refined argument handling for shorthand commands

# Copyright

vgstash is Copyright © 2016 Ze Libertine Gamer. It is licensed under the GNU
General Public License, version 3.0. A copy of this license may be found in the
`COPYING` file within this project. It may also be found on the World Wide Web
at http://gnu.org/licenses/gpl-3.0.html.