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 Luise, 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).

You can even export all *ck* data with the =export= action. This will create a
=.tar.gz= file.

** 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 manpage [[#manpage][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
Or if you want to run a particular regression test use the filter option
#+BEGIN_SRC sh
$ ./test-ck -f add
#+END_SRC
This will match any test scrits with =add= in their name.


*** 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
  -f, --filter  run regression test matching the argument
  -c, --clear           remove test files
                         use if the tests crush unexpectedly
  -v, --verbose         verbose test output
  -h, --help, *         print this
#+END_SRC
* ck configuration
See the [[#manpage][manpage]] below.

* Usage
  :PROPERTIES:
  :CUSTOM_ID: usage
  :END:
ck's goal is to assist with the configuration file management.

This section is an example usage.
** Initialize
#+BEGIN_SRC sh
  cd ~
  # make the directories for the configs
  $ mkdir -p configs/vc configs/sec

  # initialize new ck
  $ ck init configs/vc configs/sec
#+END_SRC

** Add configs
#+BEGIN_SRC sh
  # 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

  # add X configs
  $ ck add X .xinitrc
  $ ck add X .Xresources

  # add ssh configs (secret)
  $ ck add ssh .ssh/config -s -p
  $ ck add ssh .ssh/authorized_keys -s
  # When running with sudo, we need to specify the ck config
  # location.
  $ sudo ck -c /home/ckuser add ssh /etc/ssh/sshd_config -s
#+END_SRC

** Using the ck actions
#+BEGIN_SRC sh
  # list the configs in a treelike structure with basename only
  $ ck list tree -b
  # or with the full path & attributes
  $ ck list tree -a

  # list only the paths in python or lisp like lists
  $ ck list paths -t lisp
  $ ck list programs -t python -b -a

  # list emacs configs
  $ ck list -p emacs

  # search the configs
  $ ck search Hostname
  $ ck search "search term with spaces"
  # escape symbols
  $ ck search \(

  # edit the primary config of emacs wiht $EDITOR
  $ ck edit emacs
  # or with vi
  $ ck e emacs --editor vi
  # run the command cat to it
  $ ck edit emacs --command cat
  # or a complex editor call
  $ ck edit emacs --command "emacsclient -a \"\" -t"
  # edit a non-primary config of ssh
  $ ck e emacs init.el
  # edit a root config
  $ ck e ssh -s

  # delete a program with all the configs
  $ ck delete emacs
  # or a specific config
  $ ck del emacs init.el

  # restore all links (on a new instalation)
  $ ck restore --all
  # restore a program's links
  $ ck r emacs

  # get help for an action
  $ ck h add
  $ ck --help e
#+END_SRC

** Copying configs to a different linux system

Using the method described below one can use ck
to copy the configs to a different linux system.
In this example we assume we have the ck instance we created
above and we want to copy some configs to our new VPS.

We will also assume that the VPS' username is different
that the one on our desktop (=ckuser= in our example).

**** Start at the desktop by exporting the ck files
#+BEGIN_SRC sh
  you@desktop -> ck export
#+END_SRC

**** Copy the resulting tar file to the server
#+BEGIN_SRC sh
  you@desktop -> scp ck.tar.gz ckuser@server:/home/ckuser
#+END_SRC

**** Now we ssh to the server
#+BEGIN_SRC sh
  you@desktop -> ssh ckuser@server
#+END_SRC

**** Start by untaring the archive & installing ck
#+BEGIN_SRC sh
  ckuser@server -> tar zxf ck.tar.gz
#+END_SRC

**** Move the //version_control_dir// and //secer_dir// to where you want them to be
**** Move the //ckrc// and //ckdb// files where you want ck config home to be
**** Edit //ckrc// and change the *home_dir* to /home/ckuser
**** Also change //secret_dir// and //version_control_dir// to where you placed them before
**** Make sure ck will find your config by default by setting the $CK_CONFIG environment variable
     Edit bashrc to make this permanent.
 #+BEGIN_SRC sh
   ckuser@server -> export CK_CONFIG=/where/you/have/ckrc/and/ckdb
 #+END_SRC

     Note, you might not have to use this if you use one of the default config locations.
     ck will first check $XDG_CONFIG_HOME/ck and then $HOME/.ck so using either one of these will do.
**** Remove any existing conflicting configs
**** Restore your configs
#+BEGIN_SRC sh
  ckuser@server -> ck restore zsh
  ckuser@server -> ck restore emacs
#+END_SRC

* manpage
  :PROPERTIES:
  :CUSTOM_ID: manpage
  :END:
#+BEGIN_SRC sh :results output html :exports results
  groff ck.1 -mandoc -Thtml
#+END_SRC