ck
- Technicalities
- Download
build it
- requirements
- make && install
for devs
- CMake options
- compiler
- tests
  - run tests
  - test suite
manual
- ck configuration
- Actions
  - init
  - add
  - list
  - search
  - edit
  - restore
manpage

ck

The Config Keeper

Have you ever wondered:

"Jeez Luiz, how can I manage all my configs across my desktop and server?"

– You

or maybe:

"How can I possibly keep all my configs in sync across computers?"

– You again

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 repo and proceed to the build section.

You can also read the manual down below.

build it

requirements

cmake
sqlite3-dev
build tools (gcc/llvm, make…)

make && install

Use -DCMAKE_INSTALL_PREFIX when running cmake to change the install path.

# 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

for devs

Please be kind to each other.

CMake options

cmake accepts the following options:

option(CK_DEBUG "Build with debug symbols, asan and warnings")
option(CK_TESTS "Make the tests")
option(CK_SHARED "Build with shared lib")

To use any one of them append it after the cmake command like so:

cmake -DCK_DEBUG=1 -DCK_TESTS=1 ~/code/ck

compiler

Pick your favorite

> export CC=clang
# or
> export CC=gcc

# 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

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:

$ ./test-ck

test suite

$ ./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

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:

# 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

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:

$ ck config ~/ ... # the default behaviour

# /someplace/else must exist or
# the action following it must be init
$ ck -c /someplace/else ...

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:

# initialize new ck
$ ck init /path_to/where_you_want/your_configs/to_be \
  /path_to/the_secret/directory

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:

# add config to ck
$ ck add program_name config_path [-s] [-p]

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:

# 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

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:

# 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

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

# 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

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:

# 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

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:

# restore progName
ck restore -p progName
# restore all
ck r all

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

ck

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ACTIONS
EXIT STATUS
FILES
BUILD VALUES
VERSION
AUTHOR

NAME

ck − manage configuration across the system

SYNOPSIS

ck [−v|−−verbose] [−c|−−config DIR] action [...]
ck [version|−−version]
ck init VERSION_CONTROL_DIR SECRET_DIR
ck add PROGRAM_NAME CONFIG_PATH [−p] [−s]
ck delete PROGRAM_NAME|{−c CONFIG_PATH}
ck list tree [−a]
ck list {-p PROGRAM_NAME}|programs|paths [−t {plain|python|lisp}] [−a]
ck list ckconf
ck edit PROGRAM_NAME [CONFIG_BASENAME]
ck search SEARCH_TERM
ck restore PROGRAM_NAME|all
ck help action

DESCRIPTION

ck manages configuration files in a Linux system. To that end it provides an action based command line interface.

ck needs a database and an rc file to run. It also needs two directories (stored in the rc file), the VERSION_CONRTOL_DIR and the SECRET_DIR. This is where the configurations will end up after they are added to ck. The init action takes care of them. For more details see the ACTIONS and FILES sections below.

In ck terms a program is an entity that has one or more configs attached to it. Each program can have exactly one primary config. Upon adding a config to ck, it is moved to the appropriate directory, and then symbolically linked back to it’s original place (ln -s).

In a later time you can sync the VERSION_CONRTOL_DIR and SECRET_DIR. You can also restore the links given these two directories and the correspondig rc file and database.

OPTIONS

Change ck behaviour using the following options. They must be present before any action.
−−verbose, −v

[WIP]
Currently prints the log. Must be the first argument in order to work.

−−config DIR, −c DIR

Use ckdb and ckrc residing in DIR instead of the default ~/.ck/.

−−version, version

Print version and licence information, and quit.

ACTIONS

Each action has several aliases. The selected action must be after the OPTIONS if any. All available actions can be seen in the SYNOPSIS section above.

Each action takes a number of arguments and flags.

Initialize ck
Create the ck database (ckdb) and initialize it. Create the ck config file (ckrc) and add the directory paths to it.

USAGE

ck init VERSION_CONTROL_DIR SECRET_DIR

ALIASES

init, i, −i

ARGUMENTS

VERSION_CONTROL_DIR

The directory where configs will be stored by default. File must exist.

SECRET_DIR

The directory where configs will be stored when using the −s flag in add. File must exist.

EXAMPLES

$ ck init /home/ckuser/configs/vc home/ckuser/configs/sec
$ ck i configs/vc configs/sec

Add config
Add a config to the database (ckdb). Each config belongs to a program. Every program can have multiple configs under it and one of them can be primary. The edit action will open the primary config by default.

USAGE

ck add PROGRAM_NAME CONFIG_PATH [−p] [−s]

ALIASES

add, a, −a

ARGUMENTS

PROGRAM_NAME

The name of the program the config belongs at.

CONFIG_PATH

Path to the config. Can be relative.

FLAGS

−s

Mark the config as secret. It will be stored on the SECRET_DIR.

−p

Mark the config as primary. The edit action will open this by default.

EXAMPLES

# add emacs configs
## primary config
$ ck add emacs ~/.emacs.d/orgconf.org -p
## secret config, with passwords
$ ck add emacs ~/.emacs.d/accounts.org -s
## another one for emacs
$ ck add emacs ~/.emacs.d/init.el

Delete config
Delete a config or a program from the database (ckdb). This will not touch the actual file and link. It is up to the user to handle it.

USAGE

ck delete PROGRAM_NAME|{−c CONFIG_PATH}

ALIASES

delete, del, d, −d

ARGUMENTS

PROGRAM_NAME

Delete the program and all it’s configs.

−c CONFIG_PATH

Delete the config. This has to be the full path of the link as shown by the list action.

EXAMPLES
$ ck delete emacs
$ ck del -c /home/ckuser/.emacs.d/init.el

List
List programs, configs and ck configuration values.

USAGE

ck list tree [−a]
ck list {-p PROGRAM_NAME}|programs|paths [−t {plain|python|lisp}] [−a]
ck list ckconf

ALIASES

list, ls, l, -ls, −l

ARGUMENTS

tree

List programs with their configs in a tree like structure.

paths

List all the config paths ck keeps track of.

programs

List all the programs ck keeps track of.

−c PROGRAM_NAME

List all the configs of PROGRAM_NAME.

ckconf

List the ck configuration values, like the VERSION_CONTROL_DIR and SECRET_DIR.

FLAGS

−t

Set the type of the list. Can be either plain (the default) a simple list, python to print it like a python array or lisp to print it like a lisp list.

−a

Add attributes to the listing (when aplicable). The attributes are [s] for secret, [p] for primary and [root] if the file is owned by the root user.

EXAMPLES

$ ck list tree -a
$ ck list paths -t lisp
$ ck list programs -t python
$ ck list -p emacs

Edit configs
Edit a config stored in ck with the $EDITOR. Edit will open the primary config of the program. If there is no primary config but the program only has one config, edit will open that. Whenever there is ambiguity, a list of possible configs will be shown.

USAGE

ck edit PROGRAM_NAME [CONFIG_BASENAME]

ALIASES

edit, e, −e

ARGUMENTS

PROGRAM_NAME

The name of the program to be edited. If the program has only one config or you want to edit the primary one, no further action is required.

CONFIG_BASENAME

The basename of the config to be edited. This has to follow the program name. It is only needed when editing a config other than the primary one.

EXAMPLES

$ ck edit emacs
$ ck e tmux .tmux.conf

Search configs
Grep through the configs. This action is equivalent to this:

$ ck ls paths | xargs grep -H -n "search term"

Thus for more advanced search through the configs one can use other programs and replace grep in the command above.

USAGE

ck search SEARCH_TERM

ALIASES

search, grep, s, −s

ARGUMENTS

SEARCH_TERM

The term you wish to search for. If it’s a phrase enclose it in "". If it’s a special character you can escape it with \ (backslash).

EXAMPLES

$ ck search "search term" $ ck search "quire"

Restore configs
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 to ck. It is useful for copying configs to a new linux installation or restoring deleted links. It can either restore a specific program or all of them.

USAGE

ck restore PROGRAM_NAME|all

ALIASES

restore, r, −r

ARGUMENTS

PROGRAM_NAME

The name of the program to be restored.

all

Restore all programs ck keeps track of.

EXAMPLES

$ ck restore all
$ ck restore -p emacs

Get help
Get help for any given action from the command line.

USAGE

ck help action

ALIASES

help, h, −−help, -h, −?

ARGUMENTS

action

Any action alias you wish to get help for.

EXAMPLES

$ ck help add
$ ck h d
$ ck --help ls

EXIT STATUS

ck shall return 0 if the action was completed without an error, -1 otherwise

FILES

By default ck will store it’s files in ~/.ck/. Using the −c|−−config one can change this.

ck generated files
~/.ck/ckrc

Store the configuration values (VERSION_CONTROL_DIR and SECRET_DIR).

~/.ck/ckdb

SQLite3 database.

User files
VERSION_CONTROL_DIR

This is where the configuration files will end up by default. It’s value is set with the init action, but can be changed by editing ckrc.

SECRET_DIR

This is where the configuration files will end up when adding them with the -s flag. It’s value is set with the init action, but can be changed by editing ckrc.

BUILD VALUES

compiler: @CMAKE_C_COMPILER@
flags: @CMAKE_C_FLAGS@

VERSION

ck version @ck_MAJOR_VERSION@.@ck_MINOR_VERSION@.@ck_PATCH_VERSION@

AUTHOR

gramanas

Table of Contents

ck

Technicalities

Download

build it

requirements

make && install

for devs

CMake options

compiler

tests

run tests

test suite

manual

ck configuration

Actions

init

add

list

search

edit

restore

manpage

ck

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

ACTIONS

EXIT STATUS

FILES

BUILD VALUES

VERSION

AUTHOR