path: root/README.org

#+OPTIONS: ^:nil num:nil
#+html: <p align="center"><img src="res/logo.png"></p>
* ck
*The Config Keeper*

Have you ever wondered:
#+BEGIN_QUOTE
 "Jeez Luiz, how can I manage all my configs across my desktop and server?"

 -- You
#+END_QUOTE

or maybe:
#+BEGIN_QUOTE
 "How can I possibly keep all my configs in sync across computers?"

 -- You again
#+END_QUOTE

*ck* is the solution you've been looking for all your life.

With it you can keep track of all the configs you cherish and love,
and store them neat and tidy in a folder you can later sync using
your favorite sync solution (git, nextcloud, rsync). You can even gift
your precious data to Google and use GDrive (//not recommended!!//).

After you create your local config db you can list them, edit them
and even search in them, all within the comforting hands of *ck*, your
faithful companion.

You can also use *ck* to store sensitive configurations (with passwords, etc)
and instruct it to save them in a different folder, so they won't be in the
same place with the normal ones (in the event you want to share your configs
with the rest of us).

** Technicalities
Upon adding a config to *ck*, it moves it to the specified folder and adds a symbolic link
back where it came from (=ln -s=).

Make sure that the target program can read it's configuration from a symlink (the vast
majority should).

** Download
Go ahead and download *ck* and give it a try. It comes with a help sub-command
that explains any inquires you might have.

Grab the latest zip/tarball from the tag section in the [[https://ubuntos.dynu.net/git/ck][repo]] and proceed to
the [[#build-instructions][build]] section.

You can also read the manual [[#manual][down below]].

* build it
  :PROPERTIES:
  :CUSTOM_ID: build-instructions
  :END:
** requirements
- cmake
- sqlite3-dev
- build tools (gcc/llvm, make...)

** make && install
Use =-DCMAKE_INSTALL_PREFIX= when running cmake to change the install path.
#+BEGIN_SRC sh
  # clone the repo
  > cd ~/code; git clone https://gitlab.com/grm-grm/ck
  # make a build directory and enter it
  > mkdir ~/ck_build; cd ~/ck_build;
  # run cmake
  > cmake ~/code/ck 
  # run make
  > make
  # install it
  > make install
  # run ck
  > ck
#+END_SRC

* for devs
Please be [[https://www.gnu.org/philosophy/kind-communication.html][kind]] to each other.
** CMake options
cmake accepts the following options:
#+BEGIN_SRC cmake
  option(CK_DEBUG "Build with debug symbols, asan and warnings")
  option(CK_TESTS "Make the tests")
  option(CK_SHARED "Build with shared lib")
#+END_SRC

To use any one of them append it after the cmake command like so:
#+BEGIN_SRC sh
  cmake -DCK_DEBUG=1 -DCK_TESTS=1 ~/code/ck
#+END_SRC

** compiler
Pick your favorite
#+BEGIN_SRC sh
  > export CC=clang
  # or
  > export CC=gcc
#+END_SRC


#+BEGIN_SRC sh
  # clone the repo
  > cd ~/code; git clone https://gitlab.com/grm-grm/ck
  # make a build directory and enter it
  > mkdir ~/ck_build; cd ~/ck_build;
  # run cmake
  > cmake -DCK_DEBUG=1 -DCK_TESTS=1 ~/code/ck
  # run make
  > make
  # check ck
  > ./test-ck
  # run ck
  > ./ck
#+END_SRC

** tests
The testing "suite" is a bash script that runs regression
and unit tests. Regression tests are under the =tests/= directory
and are bash scripts that test =ck= functionality. Unit tests reside
under =unit/= directory and test the code.

*** run tests
First make sure you build ck with the =-DCK_TESTS=1= option. Then
go to the build directory and type:
#+BEGIN_SRC sh
$ ./test-ck
#+END_SRC

*** test suite
#+BEGIN_SRC sh
$ ./test-ck -h
ck test suite
use without flags to run all tests

flags:
  -u, --unit            run only the unit tests
  -r, --regression      run only the regression tests
  -c, --clear           remove test files
             		 use if the tests crush unexpectedly
  -h, --help, *         print this
#+END_SRC
* manual
  :PROPERTIES:
  :CUSTOM_ID: manual
  :END:
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
  $ ck list -p emacs

  # 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/delete
configuration files to/from 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 *-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 -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

Adds a configuration to the ck database.
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

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 stuff ck knows about.

You can use the keywords:
- *paths*: to print all the paths ck tracks
- *programs*: to print all the programs ck tracks
- *-p progName*: (without the "<>") to print the paths of a specific program

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, in a treelike structure.

Passing the *-a* flag will enable the listing of config attributes (secret or primary). 
It is best used with tree or plain paths.

With the keyword *ckconf* ck will list it's own configuration values (in ckrc).

Usage:
#+BEGIN_SRC sh
  # list tree structure, with attributes
  $ ck list tree -a
  # list paths in python
  $ ck l paths -t python
  # list programs in lisp
  $ ck ls programs -t lisp
  # list emacs' configurations [with attributes]
  $ ck ls -p emacs [-a]
  # list bash configurations in lisp
  $ ck ls -p bash -t lisp
  # list ck configuration
  $ ck -l ckconf
#+END_SRC

*** search
or grep 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 quotes.

Usage:
#+BEGIN_SRC sh
  # search for parenthesis
  $ ck search \(
  # search term with spaces
  $ ck grep "This is a space"
  # both
  $ ck s "(add 2 4)"
  # and a normal one
  $ ck -s alias
#+END_SRC

If you want to use more advanced grep techniques or even
a different pattern matching program you can do it like so:

#+BEGIN_SRC sh
  # with xargs
  $ ck ls paths | xargs grep -E 'A|B'
  # or in bash
  $ for i in $(ck ls paths); do grep -E 'A|B' $i; done
  # or in zsh
  $ for i ($(ck ls paths)) grep -E 'A|B' $i
#+END_SRC

*** edit 
or e or -e

Edit configurations with =$EDITOR=.

Edit takes at least one and up to two arguments.

The first argument is the *programName*. If the program has a primary configuration
edit will open this. If the program has only one configuration edit will open it. 
If the program has more than 1 configurations and no primary, it will print the 
avaliable configurations and exit.

The second argument is the *configName*. If it exists it will open, else it will 
print the avaliable configurations and exit.

Usage:
#+BEGIN_SRC sh
# suppose this is our ck instance
$ ck list tree -a
emacs:
|- init.el
|- accounts.el [s]
|- orgconf.org [p]

# edit the primary emacs config
$ ck edit emacs

# edit a specific emacs config, other than the primary
$ ck edit emacs accounts.el
#+END_SRC

*** restore
or r or -r

Restore links.

Given a working ck instance (ckdb + ckrc + directories in ckrc with configs)
restore shall recreate the links from the config directories in ckrc
back to their corresponding position when added in ck.

It is useful for copying your configs to a new linux installation
or restoring deleted links.

It can either restore a specific program or all of them:
#+BEGIN_SRC sh
  # restore progName
  ck restore -p progName
  # restore all
  ck r all
#+END_SRC

Note:
If ck tracks configs that are owned by root, simply running
`ck restore ...` will fail due to permissions. To remedy this, ck will alter the
owner and group of a link to match the one in the ckrc directories.
Thus, running `sudo ck -c /home/myuser/.ck restore ..` will restore
the root user's links as it should and the user links will have
the user as the owner instead of the root.

ck checks that the configs exist and that the location for the link
is avaliable before making any links. However, in the even that symlink
fails for some other reason, the process will stop as is. Make sure you
take care of the already created links, if that's the case.
* manpage
#+BEGIN_SRC sh :results output html :exports results
  groff ck.1 -mandoc -Thtml
#+END_SRC