diff options
| -rw-r--r-- | README.md | 55 |
1 files changed, 28 insertions, 27 deletions
@@ -1,15 +1,16 @@ # vgstash - a place to stash your game collection If you love video games, you've probably amassed a collection of them, across -many different systems; physical, digital, and everything in-between. At some -point, a player may want to know a few key pieces of information that may steer -their gaming. These questions are great for quelling boredom and keeping a -gaming backlog manageable: +many different systems and platforms, both physical and digital. At some point, +a player may want to know a few key pieces of information that may steer their +gaming. These questions are great for quelling boredom and keeping a gaming +backlog manageable: * Which games do I own? * Which games have I beaten or completed? * Which games do I need to beat? * What was the note I left for X game? +* Which games do I have more than one copy of? vgstash seeks to answer these type of questions in a simple and extensible way. @@ -21,8 +22,8 @@ vgstash is available via `pip`: pip install [--user] vgstash ~~~ -Please note that vgstash is under heavy development at present. Do not install -unless you are interested in helping its development. +Once everything's installed, just run `vgstash init` from a shell to get +started. # Concept @@ -57,7 +58,7 @@ vgstash tracks it somewhat like this: '--------------------------------------------------------' ``` -This is the bare minimum information you need to meaningfully track a video +This is the bare minimum information you need to meaningfully track a video game in your collection. # Command Line Usage @@ -78,13 +79,13 @@ tuned to match the user's preferences. ## Quoting Game Titles -A note on characters: some shells treat certain characters differently. The most -common ones you'll run into are punctuation, like single quotes ('), double -quotes (") and exclamation points (!). You'll need to search your shell's manual +A note on characters: some shells treat certain characters differently. The most +common ones you'll run into are punctuation, like single quotes ('), double +quotes (") and exclamation points (!). You'll need to search your shell's manual for "character escaping" to get the details. -Let's take a few game titles that might be problematic for a shell, and add them -to vgstash. These examples assume you're using bash (the Bourne Again SHell) or +Let's take a few game titles that might be problematic for a shell, and add them +to vgstash. These examples assume you're using bash (the Bourne Again SHell) or something comparable. First: a title with single quotes and exclamation points: @@ -101,14 +102,14 @@ Next is a little more insidious: a title with two (or more) exclamation points: $ vgstash add 'Mario Kart: Double Dash!!' GCN p n ``` -Note that we're using single quotes; if we used double quotes, then the `!!` +Note that we're using single quotes; if we used double quotes, then the `!!` would expand to the last command entered into the shell, creating `Mario Kart: Double Dash<your last command here>`. Quite different from what you'd expect! -But what if we, somehow, had both single quotes *and* sequential exclamation -points? Single-quoted strings cannot escape a single quote character. Double -quotes won't stop the `!!` expansion. Escaping the exclamation points retains +But what if we, somehow, had both single quotes *and* sequential exclamation +points? Single-quoted strings cannot escape a single quote character. Double +quotes won't stop the `!!` expansion. Escaping the exclamation points retains the backslash; what is one to do? There are a few ways to tackle this one: ```bash @@ -122,18 +123,18 @@ $ vgstash add Some\ title\'s\ crazy\!\! PC d n $ vgstash add "Some title"\''s crazy!!' PC d n ``` -The `$'text'` form is handy when you need to use double and/or single quotes -alongside exclamation points, or you can just escape every special character +The `$'text'` form is handy when you need to use double and/or single quotes +alongside exclamation points, or you can just escape every special character (including space) as needed. -The "exotic" one takes advantage of the shell's built-in string concatenation -and the ability to mix quoting styles. First we have `Some title` in double -quotes; then an escaped single quote for literal output; then `s crazy!!` in +The "exotic" one takes advantage of the shell's built-in string concatenation +and the ability to mix quoting styles. First we have `Some title` in double +quotes; then an escaped single quote for literal output; then `s crazy!!` in single quotes to avoid the `!!` expansion. -The last option is to disable the feature (history expansion) altogether, though +The last option is to disable the feature (history expansion) altogether, though you'll miss out on nice stuff like `sudo !!`. In bash, it's disabled with `set -+H` or `set +o histexpand`. Change `+` to `-` to turn it back on when you're ++H` or `set +o histexpand`. Change `+` to `-` to turn it back on when you're done. These tips may not work in all shells, so try using `echo` to print the title @@ -149,7 +150,7 @@ $ vgstash delete "my gamels" PC Removed my gamels for PC from your collection. ``` -That's it! This is something that the shell does before vgstash begins +That's it! This is something that the shell does before vgstash begins processing its arguments, so please don't report any bugs dealing with quoting. # Commands @@ -164,8 +165,8 @@ vgstash has a fairly small set of commands: * notes * update -The power is in the `list` command. vgstash comes with a set of default filters -that allow you to reason about your game collection. For example, this command +The power is in the `list` command. vgstash comes with a set of default filters +that allow you to reason about your game collection. For example, this command will show you every game marked "playing" that you also own in some way: ```bash @@ -189,11 +190,11 @@ These are planned for the full 0.3 release: * command line interface finished * Match feature-set with `master` -* Iron out any initial bugs on Windows and Mac (testers welcome!) Goals planned for the 0.4 release: * import and export with JSON +* Iron out any initial bugs on Windows and Mac (testers welcome!) Goals planned for the 0.5 release: |