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 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

*** 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
* 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
  $ ck edit emacs
  # edit a non-primary config of ssh
  $ ck e ssh authorized_keys
  # edit a root config
  $ sudo ck -c /home/ckuser e ssh sshd_config

  # 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 -p emacs

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

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