path: root/ck.1

.TH ck 1 "2018-10-27" Linux "ck - the config keeper"
.SH NAME
ck \- manage configuration across the system
.SH SYNOPSIS
.B ck
.RB [ \-v | \-\-verbose ]
.RB [ \-c | \-\-config
.IR DIR ]
.IR action \ [.\|.\|.]
.br
.B ck
.RB [ version | \-\-version ]
.br
.B ck init
.I VERSION_CONTROL_DIR SECRET_DIR
.br
.B ck add
.I PROGRAM_NAME CONFIG_PATH
.RB [ \-p ]
.RB [ \-s ]
.br
.B ck delete
.IR PROGRAM_NAME | \fR{\fB\-c \ \fICONFIG_PATH\fR}
.br
.B ck list
.BR tree \ [ \-a ]
.RB [ \-b ]
.br
.B ck list
.RB { -p \ \fIPROGRAM_NAME\fR}\fR| programs | paths \ [ \-t
.RB { plain | python | lisp } \fR]
.RB [ \-a ]
.RB [ \-b ]
.br
.B ck list ckconf
.br
.B ck edit
.IR PROGRAM_NAME \ [ CONFIG_BASENAME ]
.br
.B ck search
.I SEARCH_TERM
.br
.B ck restore
.IR PROGRAM_NAME | \fBall
.br
.B ck help
.I action
.SH DESCRIPTION
.B ck
manages configuration files in a Linux system. To that end it provides an
.B action
based command line interface.
.P
.B ck
needs a database and an rc file to run. It also needs two
directories (stored in the rc file), the
.I VERSION_CONRTOL_DIR
and the
.IR SECRET_DIR .
This is where the configurations will end up after they are added to
.BR ck .
The
.B init
action takes care of them. For more details see the
.BR ACTIONS \ and \ FILES
sections below.
.P
In
.B ck
terms a
.I program
is an entity that has one or more
.I configs
attached to it. Each
.I program
can have exactly one
.BI primary \ config \fR.
Upon adding a
.I config
to
.BR ck ,
it is moved to the appropriate directory, and then symbolically linked
back to it's original place (\fIln -s\fR).
.P
In a later time you can sync the
.I VERSION_CONRTOL_DIR
and
.IR SECRET_DIR .
You can also
.B restore
the links given these two directories and the correspondig rc file and database.

.SH CONFIGURATION
.B ck
uses
.B sqlite
to index the configuration files. The
.B init action
by default creates a directory named
.I .ck
under
.I $HOME
in witch the
.I ckrc
and
.I ckdb
files reside. See the
.B FILES
section for more details.
.P
One can have multiple
.B config directories
with different configurations each.
Using the
.BR config \ or \ \-c
option one can set the path
in which ck will search for
.I ckrc
and
.IR ckdb .
See the
.B OPTIONS
section for more details.
.P
.SH OPTIONS
Change
.B ck
behaviour using the following options. They must be present before any
.B action.
.TP
.B \-\-verbose\fR, \fB\-v
[WIP]
.br
Currently prints the log. Must be the first argument in order to work.
.TP
.B \-\-config \fIDIR\fR, \fB\-c \fIDIR
Use
.BR ckdb \ and \ ckrc
residing in
.I DIR
instead of the default
.IR ~/.ck/ .
.TP
.B \-\-version\fR, \fBversion
Print version and licence information, and quit.
.SH ACTIONS
Each
.B action
has several aliases. The selected
.B action
must be after the
.B OPTIONS
if any. All available
.B actions
can be seen in the
.B SYNOPSIS
section above.
.P
Each
.B action
takes a number of arguments and flags.
.SS "Initialize ck"
Create the
.B ck
database
.RI ( ckdb )
and initialize it. Create the ck config file
.RI ( ckrc )
and add the directory paths to it.
.TP 2
.B USAGE
.B ck init
.I VERSION_CONTROL_DIR SECRET_DIR
.TP 2
.B ALIASES
.BR init , \ i , \ \-i
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I VERSION_CONTROL_DIR
The directory where
.B configs
will be stored by default.
.B File must exist\fR.
.TP 21
.I SECRET_DIR
The directory where
.B configs
will be stored when using the
.B \-s
flag in
.B add\fR. \fBFile must exist\fR.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck init /home/ckuser/configs/vc home/ckuser/configs/sec
$ ck i configs/vc configs/sec
.EE
.SS "Add config"
Add a
.B config
to the database
.RI ( ckdb )\fR.
Each
.B config
belongs to a
.BR program .
Every \fBprogram\fR can have
multiple
.B configs
under it and one of them can be
.BR primary .
The
.B edit action
will open the
.B primary config
by default.
.TP 2
.B USAGE
.B ck add
.I PROGRAM_NAME CONFIG_PATH
.RB [ \-p ]
.RB [ \-s ]
.TP 2
.B ALIASES
.BR add , \ a , \ \-a
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I PROGRAM_NAME
The name of the
.B program
the
.B config
belongs at.
.TP 21
.I CONFIG_PATH
Path to the
.BR config .
Can be relative.
.RE
.TP 2
.B FLAGS
.ns
.RS 2
.TP 21
.B \-s
Mark the
.B config
as secret. It will be stored
on the
.IR SECRET_DIR .
.TP 21
.B \-p
Mark the
.B config
as primary. The
.B edit action
will open this by default.
.RE
.TP 2
.B EXAMPLES
.EX
# 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
.EE
.SS "Delete config"
Delete a
.B config
or a
.B program
from the database
.RI ( ckdb )\fR.
This will not touch the actual file and link. It is up to the user
to handle it.
.P
.B USAGE
.in +.2i
.B ck delete
.IR PROGRAM_NAME | \fR{\fB\-c \ \fICONFIG_PATH\fR}
.P
.B ALIASES
.in +.2i
.BR delete , \ del , \ d , \ \-d
.P
.B ARGUMENTS
.in +.2i
.I PROGRAM_NAME
.br
.in +.2i
Delete the
.B program
and all it's
.BR configs .
.P
.in +.2i
.BI \-c \ CONFIG_PATH
.in +.2i
Delete the
.BR config .
This has to be the full path of the link as shown by the
.B list action\fR.
.P
.B EXAMPLES
.br
$ ck delete emacs
.br
$ ck del -c /home/ckuser/.emacs.d/init.el
.SS "List"
List programs, configs and ck configuration values.
.P
.B USAGE
.br
.in +.2i
.B ck list
.BR tree \ [ \-a ]
.RB [ \-b ]
.br
.B ck list
.RB { -p \ \fIPROGRAM_NAME\fR}\fR| programs | paths \ [ \-t
.RB { plain | python | lisp } \fR]
.RB [ \-a ]
.RB [ \-b ]
.br
.B ck list ckconf
.br
.P
.B ALIASES
.in +.2i
.BR list , \ ls , \ l , \ -ls , \ \-l
.P
.B ARGUMENTS
.in +.2i
.B tree
.in +.2i
List
.B programs
with their
.B configs
in a tree like structure.
.P
.in +.2i
.B paths
.in +.2i
List all the
.B config
paths
.B ck
keeps track of.
.P
.in +.2i
.B programs
.in +.2i
List all the
.B programs ck
keeps track of.
.P
.in +.2i
.BI \-c \ PROGRAM_NAME
.in +.2i
List all the
.B configs
of
.IR PROGRAM_NAME .
.P
.in +.2i
.BI ckconf
.in +.2i
List the
.B ck
configuration values, like the
.IR VERSION_CONTROL_DIR \ and \ SECRET_DIR .
.P
.B FLAGS
.in +.2i
.B \-t
.in +.2i
Set the type of the
.BR list .
Can be either
.B plain
(the default) a simple list,
.B python
to print it like a python array or
.B lisp
to print it like a lisp list.
.P
.in +.2i
.B \-a
.in +.2i
Add attributes to the listing (when aplicable).
The attributes are
.B [s]
for
.BR secret ,
.B [p]
for
.B primary
and
.B [root]
if the file is owned by the root user.
.P
.in +.2i
.B \-b
.in +.2i
Print the
.B config
basename instead of the full path.
.P
.B EXAMPLES
.in +.2i
$ ck list tree -a
.br
$ ck list paths -t lisp
.br
$ ck list programs -t python
.br
$ ck list -p emacs
.SS "Edit configs"
Edit a
.B config
stored in
.B ck
with the
.IR $EDITOR .
.B Edit
will open the
.B primary config
of the
.BR program .
If there is no
.B primary config
but the
.B program
only has one
.BR config ,
.B edit
will open that.
Whenever there is ambiguity, a list
of possible
.B configs
will be shown.
.P
.B USAGE
.br
.in +.2i
.B ck edit
.IR PROGRAM_NAME \ [ CONFIG_BASENAME ]
.br
.P
.B ALIASES
.in +.2i
.BR edit , \ e , \ \-e
.P
.B ARGUMENTS
.in +.2i
.I PROGRAM_NAME
.in +.2i
The name of the
.B program
to be edited. If the
.B program
has only one
.B config
or you want to edit the
.B primary
one, no further action is required.
.P
.in +.2i
.I CONFIG_BASENAME
.in +.2i
The basename of the
.B config
to be edited. This has to follow the
.B program
name. It is only needed when editing a
.B config
other than the
.B primary
one.
.P
.B EXAMPLES
.in +.2i
$ ck edit emacs
.br
$ ck e tmux .tmux.conf
.SS "Search configs"
Grep through the configs. This
.B action
is equivalent to this:
.P
$ ck ls paths | xargs grep -H -n "search term"
.P
Thus for more advanced search through the
.B configs
one can use other programs and replace grep in the command above.
.P
.B USAGE
.br
.in +.2i
.B ck search
.I SEARCH_TERM
.br
.P
.B ALIASES
.in +.2i
.BR search , \ grep , \ s , \ \-s
.P
.B ARGUMENTS
.in +.2i
.I SEARCH_TERM
.in +.2i
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).
.P
.B EXAMPLES
.in +.2i
$ ck search "search term"
.br
$ ck search "\\(require"
.SS "Restore configs"
Given a working
.B ck
instance (\fIckdb \fR+ \fIckrc\fR + directories in \fIckrc\fR with
.BR configs ), \ restore
shall recreate the links from the
.B config
directories in
.I ckrc
back to their corresponding position when added to
.BR ck .
It is useful for copying
.B configs
to a new linux installation or
.B restoring
deleted links. It can either
.B restore
a specific
.B program
or all of them.
.P
.BR NOTE :
If
.B ck
tracks
.B configs
that are owned by root, simply running
.br
.in +.2i
$ ck restore \.\.\.
.in
.br
will fail due to permissions. To remedy this,
.B ck
will alter the
.BR owner \ and \ group
of a link to match the one in the original
.B config
file.
Thus, running
.in +.2i
$ sudo ck -c /home/ckuser/.ck restore \.\.\.
.in
will
.B restore
the root user's links as it should and the user links will have
the user as the owner instead of the root.
.P
.B ck
checks that the
.B configs
exist and that the location for the link
is avaliable before making any links. However, in the even that
.B symlink
fails for some other reason, the process will stop as is. The user will have to
take care of the already created links, if that's the case.
.P
.B USAGE
.br
.in +.2i
.B ck restore
.IR PROGRAM_NAME | \fBall
.br
.P
.B ALIASES
.in +.2i
.BR restore , \ r , \ \-r
.P
.B ARGUMENTS
.in +.2i
.I PROGRAM_NAME
.in +.2i
The name of the
.B program
to be restored.
.P
.in +.2i
.B all
.in +.2i
Restore all
.B programs ck
keeps track of.
.P
.B EXAMPLES
.in +.2i
$ ck restore all
.br
$ ck restore -p emacs
.SS "Get help"
Get help for any given
.B action
from the command line.
.P
.B USAGE
.br
.in +.2i
.B ck help
.I action
.P
.B ALIASES
.in +.2i
.BR help , \ h , \ \-\-help , \ -h , \ \-?
.P
.B ARGUMENTS
.in +.2i
.I action
.in +.2i
Any
.B action alias
you wish to get help for.
.P
.B EXAMPLES
.in +.2i
$ ck help add
.br
$ ck h d
.br
$ ck --help ls
.SH EXIT STATUS
.B ck
shall return 0 if the action was completed without an error, -1 otherwise
.SH FILES
By default
.B ck
will store it's files in
.IR ~/.ck/ .
Using the
.BR \-c | \-\-config
one can change this.
.SS "ck generated files"
.TP
.I ~/.ck/ckrc
Store the configuration values (\fIVERSION_CONTROL_DIR\fR and \fISECRET_DIR\fR).
.TP
.I ~/.ck/ckdb
SQLite3 database.
.SS "User files"
.TP
.I VERSION_CONTROL_DIR
This is where the configuration files will end up by default. It's value is set with the
.B init
action, but can be changed by editing
.IR ckrc .
.TP
.I SECRET_DIR
This is where the configuration files will end up when adding them with the
.B -s
flag. It's value is set with the
.B init
action, but can be changed by editing
.IR ckrc .
.SH BUILD VALUES
.BR compiler :
@CMAKE_C_COMPILER@
.br
.BR flags :
@CMAKE_C_FLAGS@
.SH VERSION
ck version @ck_MAJOR_VERSION@.@ck_MINOR_VERSION@.@ck_PATCH_VERSION@
.SH AUTHOR
gramanas