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
.SY ck
.OP \-v\fR|\fB\-\-verbose
.OP \-c\fR|\fB\-\-config DIR
.IR action \ [.\|.\|.]
.YS
.ns
.SY ck
.OP version\fR|\fB\-\-version
.YS
\" Init
.SY ck
.B init
.I VERSION_CONTROL_DIR
.RI [ SECRET_DIR ]
.YS
\" Add
.SY ck
.B add
.I PROGRAM_NAME CONFIG_PATH
.OP \-p
.OP \-s
.YS
\" Delete
.SY ck
.B delete
.I PROGRAM_NAME
.RI [ CONFIG_BASENAME ]
.YS
\" List
.SY ck
.B list tree
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.BI \-p \ PROGRAM_NAME
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.B programs
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.B paths
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list ckconf
.YS
\" Edit
.SY ck
.B edit
.I PROGRAM_NAME
.RI [ CONFIG_BASENAME ]
.OP \-\-editor EDITOR
.OP \-\-command COMMAND
.OP \-s
.YS
\" Search
.SY ck
.B search
.I SEARCH_TERM
.YS
\" Restore
.SY ck
.B restore \-p
.I PROGRAM_NAME
.YS
.ns
.SY ck
.B restore all
.YS
\" Help
.SY ck
.BI help \ action
.YS
\" Export
.SY ck
.B export
.YS
.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 (optionally) 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_CONTROL_DIR
and
.IR SECRET_DIR .
You can also
.B restore
the links given these two directories and the corresponding 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
in witch the
.I ckrc
and
.I ckdb
files reside. See the
.B FILES
section for more details.
.P
.B ck
will first search for the configuration in the folder shown by the
.I $CK_CONFIG
environment variable. If it is set it will use the
.I ckrc
and
.I ckdb
inside this directory. Else it will use
.I $XDG_CONFIG_HOME/ck
and if that is not set as well it will fall back to
.IR $HOME/.ck .
.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 .
Using this will ignore any environment variables. See the
.B OPTIONS
section for more details.
.P
.SH OPTIONS
Change
.B ck
behavior 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
.IR DIR .
.TP
.B \-\-version\fR, \fBversion
Print version and license 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"
Create the
.B ck
database
.RI ( ckdb )
and initialize it. Create the ck config file
.RI ( ckrc )
and add the directory paths to it. If
.I SECRET_DIR
is not passed, the
.B \-s
flag will be disabled in the
.B add
action, and this
.B ck
instance won't be able to
store secret configs.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B init
.I VERSION_CONTROL_DIR
.RI [ SECRET_DIR ]
.YS
.RE
.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
$ ck i ~/scripts # no secret dir provided
.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
.ns
.RS 2
.SY ck
.B add
.I PROGRAM_NAME CONFIG_PATH
.OP \-p
.OP \-s
.YS
.RE
.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.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B delete
.I PROGRAM_NAME
.RI [ CONFIG_BASENAME ]
.YS
.RE
.TP 2
.B ALIASES
.BR delete , \ del , \ d , \ \-d
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I PROGRAM_NAME
Delete the
.B program
and all it's
.BR configs .
.TP 21
.I CONFIG_BASENAME
The basename of the
.B config
file to be deleted. It has to follow the
.IR PROGRAM_NAME .
.RE
.TP 2
.B EXAMPLES
.EX
$ ck delete emacs
$ ck del emacs init.el
.EE
.SS "LIST VALUES"
List programs, configs and ck configuration values.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B list tree
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.BI \-p \ PROGRAM_NAME
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.B programs
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list
.B paths
.OP \-t list-type
.OP \-a
.OP \-b
.YS
.ns
.SY ck
.B list ckconf
.YS
.RE
.TP 2
.B ALIASES
.BR list , \ ls , \ l , \ -ls , \ \-l
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.B tree
List
.B programs
with their
.B configs
in a tree like structure.
.TP 21
.B paths
List all the
.B config
paths
.B ck
keeps track of.
.TP 21
.B programs
List all the
.B programs ck
keeps track of.
.TP 21
.BI \-c \ PROGRAM_NAME
List all the
.B configs
of
.IR PROGRAM_NAME .
.TP 21
.BI ckconf
List the
.B ck
configuration values, like the
.IR VERSION_CONTROL_DIR \ and \ SECRET_DIR .
.RE
.TP 2
.B FLAGS
.ns
.RS 2
.TP 21
.BI \-t \ type
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.
.TP 21
.B \-a
Show attributes to the listing (when applicable).
These are
.B [s]
for
.BR secret ,
.B [p]
for
.B primary
and
.B [root]
if the file is owned by the root user.
.TP 21
.B \-b
Print the
.B config
basename instead of the full path.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck list tree -a
$ ck list paths -t lisp
$ ck list programs -t python
$ ck list -p emacs
.EE
.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.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B edit
.I PROGRAM_NAME
.RI [ CONFIG_BASENAME ]
.OP \-\-editor EDITOR
.OP \-\-command COMMAND
.OP \-s
.YS
.RE
.TP 2
.B ALIASES
.BR edit , \ e , \ \-e
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I PROGRAM_NAME
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.
.TP 21
.I CONFIG_BASENAME
The basename of the
.B config
to be edited. This has to follow the
.I PROGRAM_NAME
name. It is only needed when editing a
.B config
other than the
.B primary
one.
.RE
.TP 2
.B FLAGS
.ns
.RS 2
.TP 21
.BI \-\-editor \ EDITOR
Use
.I EDITOR
to edit the config.
.TP 21
.BI \-\-command \ COMMAND
The
.I COMMAND
string will be used instead of an editor.
.TP 21
.B \-\-s
Prepend the whole command with sudo, should you want to edit a
.B config
belonging to root.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck edit emacs
$ ck edit emacs --command cat
$ ck edit emacs --command "emacsclient -a \"\" -t"
$ ck e tmux .tmux.conf
$ ck e tmux .tmux.conf --editor vi
$ ck e ssh -s
.EE
.SS "SEARCH CONFIGS"
Grep through the configs. This
.B action
is equivalent to this:
.br
.RS 2
$ ck ls paths | xargs grep -H -n "search term"
.RE
.br
Thus for more advanced search through the
.B configs
one can use other programs and replace grep in the command above.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B search
.I SEARCH_TERM
.YS
.RE
.TP 2
.B ALIASES
.BR search , \ grep , \ s , \ \-s
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I 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).
.RE
.TP 2
.B EXAMPLES
.EX
$ ck search "search term"
$ ck search "\\(require"
.EE
.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
.RS 2
$ ck restore \.\.\.
.RE
.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
.RS 2
$ sudo ck -c /home/ckuser/.ck restore \.\.\.
.RE
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 available 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.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B restore \-p
.I PROGRAM_NAME
.YS
.ns
.SY ck
.B restore all
.YS
.RE
.TP 2
.B ALIASES
.BR restore , \ r , \ \-r
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I PROGRAM_NAME
The name of the
.B program
to be restored.
.TP 21
.B all
Restore all
.B programs ck
keeps track of.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck restore all
$ ck restore -p emacs
.EE
.SS "GET HELP"
Get help for any given
.B action
from the command line.
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.BI help \ action
.YS
.RE
.TP 2
.B ALIASES
.BR help , \ h , \ \-\-help , \ -h , \ \-?
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
.I action
Any
.B action alias
you wish to get help for.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck help add
$ ck h d
$ ck --help ls
.EE
.SS "EXPORT CONFIGS"
.B ck
can export the config files it tracks as well as the
.I ckrc
and
.I ckdb
files into a tar.gz archive. The file is named ck.tar.gz
.TP 2
.B USAGE
.ns
.RS 2
.SY ck
.B export
.YS
.RE
.TP 2
.B ALIASES
.BR export , \ \-\-export , \ \-ex
.TP 2
.B ARGUMENTS
.ns
.RS 2
.TP 21
None.
.RE
.TP 2
.B EXAMPLES
.EX
$ ck export
.EE
.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
.I $CK_CONFIG
>
.I $XDG_CONFIG_HOME/ck
>
.IR $HOME/.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