From be408978f54f83d393494d9ca263b88d4c596725 Mon Sep 17 00:00:00 2001 From: Anastasis Grammenos Date: Sun, 23 Sep 2018 00:03:05 +0300 Subject: update readme & add manual --- README.org | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) (limited to 'README.org') diff --git a/README.org b/README.org index 9f83ddc..13becc6 100644 --- a/README.org +++ b/README.org @@ -68,3 +68,172 @@ flags: use it if the tests fail -h, --help, * print this #+END_SRC +* manual +ck's goal is to assist with the configuration file management. +To that end it tries to provides a cli interface that is pretty straight-forward +and intuitive. + +Example usage: +#+BEGIN_SRC sh + # initialize new ck + $ ck init /path_to/where_you_want/your_configs/to_be \ + /path_to/the_secret/directory + + # add emacs configs + ## primary config + $ ck add emacs ~/.emacs.d/orgconf.org -p + ## secret config, with passwords and naughty words + $ ck add emacs ~/.emacs.d/accounts.org -s + ## and another one for emacs + $ ck add emacs ~/.emacs.d/init.el + + # add tmux config + $ ck add tmux ~/.tmux.conf -p + + # list the configs + $ ck list tree + $ ck list paths -t lisp + $ ck list programs -t python + + # search the configs + $ ck search search-term + $ ck search "\"search term with spaces\"" + $ ck search "\(" #escape symbols +#+END_SRC + +The first command after typing *ck* is the action you wish to perform. Actions are +a very important concept of ck. With an action you can initialize *ck*, add/move/delete +configuration files to it, edit them, list them in various ways and search in their content. + +Actions expect their arguments in the order specified below. This is done to reduce the amount +of flags one has to pass to ck. + +** ck configuration +ck uses sqlite to index the configuration files. The init +action creates a *.ck* directory (under $HOME) +in witch the *ckrc* and the *ckdb* reside. The first one contains +the two directories described above while the other one is the +sqlite db. + +One can have multiple config directories with different configurations +each. + +Using the special keyword *config* (or *conf* or *c* or *-c*) you can set the path +in which ck will search for the *.ck* directory. + +You can prefix every action with this and ck will use the configuration +directory of your choice. + +Usage: +#+BEGIN_SRC sh + $ ck config ~/ ... # the default behaviour + + # /someplace/else must exist or + # the action following it must be init + $ ck conf /someplace/else ... + + # same thing + $ ck c /someplace/else ... + $ ck -c /someplace/else ... +#+END_SRC + +** Actions +*** init +or i or -i + +init takes exactly 2 arguments. + +- *config_dir*: where all the configs will live +- *secret_dir*: where all the secret configs will live + +Use init to initialize a new ck database. + +Usage: +#+BEGIN_SRC sh + # initialize new ck + $ ck init /path_to/where_you_want/your_configs/to_be \ + /path_to/the_secret/directory +#+END_SRC + +*** add +or a or -a + +Add takes 2 to 4 arguments. + +- *program_name*: the name of the program you add a config to +- *config_path*: the path to the config +- Optional: (order doesn't matter) + + *-p*: the config will be the primary (relevant on edit below) + + *-s*: the config will be stored in the secret_dir + +Use add to add a new config for ck to keep track of. + +Keep in mind: +- The config has to exist +- If you are adding a config to a program already existing in ckdb make + sure to use the same name +- Each program can have only one primary config + +Usage: +#+BEGIN_SRC sh + # add config to ck + $ ck add program_name config_path [-s] [-p] +#+END_SRC + +*** list +or ls or l or -l + +List can show the *paths* or the *programs* that ck keeps track of. +With the flag *-t* and then one of the follwing types one can change +the way the list is printed: +- *plain*: simple listing (default) +- *python*: print like a python list +- *lisp*: print like a lisp list + +Using the keyword *tree* ck can list the configurations under their +corresponding program. + +#+BEGIN_SRC C + /* TODO: show primary and secret atributes */ +#+END_SRC +Usage: +#+BEGIN_SRC sh + # list tree structure + $ ck list tree + # list paths in python + $ ck l paths -t python + # list programs in lisp + $ ck ls programs -t lisp +#+END_SRC + +*** search +or s or -s + +Perform infile grep in all the configurations ck keeps track of. + +Takes one argument, the *search-term*. + +To search for terms with spaces you have to put them in escaped quotes. +To search for special symbols you have to enclose them in quotes and escape them. + +Usage: +#+BEGIN_SRC sh + # search for parenthesis + $ ck search "\(" + # search term with spaces + $ ck search "\"This is a space\"" + # both + $ ck search "\"(add 2 4)\"" + # and a normal one + $ ck search alias +#+END_SRC + +*** edit +or e or -e +~~--WIP--~~ +Currently edit can only edit the primary config of a program. + +To do it use: +#+BEGIN_SRC sh +$ ck edit program_name +#+END_SRC -- cgit v1.2.3