The ascii-invoicer is a command-line tool that manages projects and stores them not in a database but in a folder structure. New projects can be created from templates and are stored in a working directory. Projects can be archived, each year will have its own archive. A project consists of a folder containing a yaml file describing it and a number of attached files, such tex files. Projects can contain products and personal. You can create preliminary offers and invoices from your projects.
Should be as easy as
$ gem install ascii_invoicer.
You might need rvm to install it in your
$HOME directory, otherwise use
$ sudo gem install ascii_invoicer.
New versions should be automatically updated via
$ gem update.
Each of these sections starts with a list of commands.
Read the help to each command with
ascii help [COMMAND] to find out about all parameters, especially list has quite a few of them.
Get started with
ascii help [COMMAND] # Describe available commands or one specific command ascii list # List current Projects ascii display NAMES # Shows information about a project in different ways
ascii new NAME # Creating a new project ascii edit NAMES # Edit project ascii offer NAMES # Create an offer from project ascii invoice NAMES # Create an invoice from project ascii archive NAME # Move project to archive ascii reopen YEAR NAME # reopen an archived project
ascii add NAMES ascii commit -m, --message=MESSAGE ascii log ascii pull ascii push ascii status
These commands behave similar to the original git commands. The only difference is that you select projects just like you do with other ascii commands (see edit, display, offer, invoice). Commit uses -m (like in git) but unlike git does not (yet) open an editor if you leave out the message.
These commands are meant as a convenience, they ARE NOT however a complete replacement for git!
You should always pull before you start working and push right after you are done in order to avoid merge conflicts.
If you do run into such problems go to storage directory
cd $(ascii path) and resolve them using git.
Personal advice N°1: use
git pull --rebase
Personal advice N°2: add this to your .bash_aliases:
alias agit="git --git-dir=$(ascii path)/.git --work-tree=$(ascii path)"
ascii list and
ascii display (equals
ascii show) allow to display all sorts of details from a project.
You can define sort of path through the document structure to the key you want to be displayed.
ascii show -d client/email will display the clients email.
ascii show -d invoice/date will display the date of the invoice.
ascii list --details will add columns to the table.
For example try
ascii list --details client/fullname client/email
ascii calendar # Create a calendar file from all caterings named "invoicer.ics" ascii csv # Prints a CSV list of current year into CSV
You can pipe the csv into column (
ascii csv | column -ts\;) to display the table in you terminal.
ascii path # Return projects storage path ascii settings # View settings ascii templates # List or add templates ascii whoami # Invoke settings --show manager_name ascii version # Display version
Your config-file is located in ~/.ascii-invoicer.yml but you can also access it using
ascii settings --edit or even
ascii edit --settings.
The projects directory contains working, archive and templates. If you start with a blank slate you might want to put the templates folder into the storage folder (not well tested yet).
By default in your
path folder you fill find:
caterings ├── archive │ ├── 2013 │ │ ├── Foobar1 │ │ │ └── Foobar1.yml │ │ └── Foobar2 │ │ ├── Foobar2.yml │ │ └── R007 Foobar2 2013-02-11.tex │ └── 2014 │ ├── canceled_foobar1 │ │ ├── A20141009-1 foobar.tex │ │ └── foobar1.yml │ ├── R029_foobar2 │ │ └── R029 foobar2 2014-09-10.tex │ └── R036_foobar3 │ ├── foobar3.yml │ └── R036 foobar3 2014-10-08.tex ├── templates │ ├── default.yml.erb │ └── document.tex.erb └── working ├── Foobar1 │ ├── A20141127-1 Foobar1.tex │ └── Foobar1.yml ├── Foobar2 │ ├── A20141124-1 Foobar2.tex │ └── Foobar2.yml └── Foobar3 ├── A20140325-1 Foobar3.tex ├── A20140327-1 Foobar3.tex ├── R008 Foobar3 2014-03-31.tex └── Foobar3.yml
repl ascii! You should copy repl-file into ~/.repl/ascii and install rlwrap to take advantage of all the repl goodness such as autocompletion and history.
xclip! You can pipe the output of
ascii show --csvto xclip and paste to your email program or into a spreadsheet tool like libreoffice calc.
Some strings may cause problems when rendering latex, e.g.
a client called
"ABC GmbH & Co. KG".
"&" causes latex to fail,
\&" bugs the yaml parser but
"\\&" will do the trick.
# lets install building dependencies cd src gem install bundler # if you don't already have it bundle install # pulls all building dependencies # actually now you're done # after you made your own changes rake install # installs the gem rake gem # builds the gem # that's it
- rvm works best, otherwise I have not tested installing it anywhere else
- a lot of latex packages to run the offer/invoice export