From 7b3eb51ec3ea3f96dc3d794e799f0d61c3e1d7be Mon Sep 17 00:00:00 2001 From: gramanas Date: Wed, 14 Nov 2018 16:42:40 +0200 Subject: XDG_CONFIG_HOME support --- README.html | 1198 ++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 857 insertions(+), 341 deletions(-) (limited to 'README.html') diff --git a/README.html b/README.html index 655204c..4c8647c 100644 --- a/README.html +++ b/README.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + ‎ @@ -232,36 +232,36 @@ for the JavaScript code in this tag.

Table of Contents

-
-

ck

-
+
+

ck

+

The Config Keeper

@@ -327,9 +327,9 @@ with the rest of us).

-
-

Technicalities

-
+
+

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). @@ -342,9 +342,9 @@ majority should).

-
-

Download

-
+
+

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. @@ -362,13 +362,13 @@ You can also read the manpage down below.

-
-

build it

+
+

build it

-
-

requirements

-
+
+

requirements

+
  • cmake
  • sqlite3-dev
    • @@ -377,24 +377,24 @@ You can also read the manpage down below.
-
-

make && install

-
+
+

make && install

+

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

-
# clone the repo
+
# 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
+# make a build directory and enter it
+> mkdir ~/ck_build; cd ~/ck_build;
+# run cmake
 > cmake ~/code/ck 
-# run make
+# run make
 > make
-# install it
+# install it
 > make install
-# run ck
+# run ck
 > ck
@@ -402,23 +402,23 @@ Use -DCMAKE_INSTALL_PREFIX when running cmake to change the install
-
-

for devs

-
+
+

for devs

+

Please be kind to each other.

-
-

CMake options

-
+
+

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")
+
option(CK_DEBUG "Build with debug symbols, asan and warnings")
+option(CK_TESTS "Make the tests")
+option(CK_SHARED "Build with shared lib")
@@ -432,41 +432,41 @@ To use any one of them append it after the cmake command like so:
-
-

compiler

-
+
+

compiler

+

Pick your favorite

-
> export CC=clang
-# or
-> export CC=gcc
+
> export CC=clang
+# or
+> export CC=gcc
-
# clone the repo
+
# 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
+# 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
+# run make
 > make
-# check ck
+# check ck
 > ./test-ck
-# run ck
+# run ck
 > ./ck
-
-

tests

-
+
+

tests

+

The testing "suite" is a bash script that runs regression and unit tests. Regression tests are under the tests/ directory @@ -475,9 +475,9 @@ under unit/ directory and test the code.

-
-

run tests

-
+
+

run tests

+

First make sure you build ck with the -DCK_TESTS=1 option. Then go to the build directory and type: @@ -489,9 +489,9 @@ go to the build directory and type:

-
-

test suite

-
+
+

test suite

+
$ ./test-ck -h
 ck test suite
@@ -509,17 +509,17 @@ flags:
-
-

ck configuration

-
+
+

ck configuration

+

See the manpage below.

-
-

Usage

+
+

Usage

ck's goal is to assist with the configuration file management. @@ -529,91 +529,91 @@ ck's goal is to assist with the configuration file management. This section is an example usage.

-
-

Initialize

-
+
+

Initialize

+
-
cd ~
-# make the directories for the configs
+
cd ~
+# make the directories for the configs
 $ mkdir -p configs/vc configs/sec
 
-# initialize new ck
+# initialize new ck
 $ ck init configs/vc configs/sec
-
-

Add configs

-
+
+

Add configs

+
-
# add emacs configs
-## primary config
+
# add emacs configs
+## primary config
 $ ck add emacs .emacs.d/orgconf.org -p
-## secret config, with passwords and naughty words
+## secret config, with passwords and naughty words
 $ ck add emacs .emacs.d/accounts.org -s
-## and another one for emacs
+## and another one for emacs
 $ ck add emacs .emacs.d/init.el
 
-# add tmux config
+# add tmux config
 $ ck add tmux .tmux.conf -p
 
-# add X configs
+# add X configs
 $ ck add X .xinitrc
 $ ck add X .Xresources
 
-# add ssh configs (secret)
+# 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.
+# When running with sudo, we need to specify the ck config
+# location.
 $ sudo ck -c /home/ckuser add ssh /etc/ssh/sshd_config -s
-
-

Using the ck actions

-
+
+

Using the ck actions

+
-
# list the configs in a treelike structure with basename only
+
# list the configs in a treelike structure with basename only
 $ ck list tree -b
-# or with the full path & attributes
+# or with the full path & attributes
 $ ck list tree -a
 
-# list only the paths in python or lisp like lists
+# 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
+# list emacs configs
 $ ck list -p emacs
 
-# search the configs
+# search the configs
 $ ck search Hostname
-$ ck search "search term with spaces"
-# escape symbols
-$ ck search \(
+$ ck search "search term with spaces"
+# escape symbols
+$ ck search \(
 
-# edit the primary config of emacs
+# edit the primary config of emacs
 $ ck edit emacs
-# edit a non-primary config of ssh
+# edit a non-primary config of ssh
 $ ck e ssh authorized_keys
-# edit a root config
+# edit a root config
 $ sudo ck -c /home/ckuser e ssh sshd_config
 
-# delete a program with all the configs
+# delete a program with all the configs
 $ ck delete emacs
-# or a specific config
+# or a specific config
 $ ck del -c /home/ckuser/.emacs.d/init.el
 
-# restore all links (on a new instalation)
+# restore all links (on a new instalation)
 $ ck restore all
-# restore a program's links
+# restore a program's links
 $ ck r -p emacs
 
-# get help for an action
+# get help for an action
 $ ck h add
 $ ck --help e
 

@@ -622,11 +622,11 @@ $ ck --help e
-
-

manpage

+
+

manpage

- + @@ -675,29 +675,216 @@ manage configuration across the system

-

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] [−b] -
-ck list -{-p PROGRAM_NAME}|programs|paths [−t -{plain|python|lisp}] [−a] -[−b]
-ck list ckconf
-ck edit -PROGRAM_NAME [CONFIG_BASENAME]
-ck search SEARCH_TERM
-ck restore PROGRAM_NAME|all
-ck help action

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

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 +[CONFIG_BASENAME]

 +
+ + +

ck

 + + +

list tree [−a] [−b]

 +
+ + +

ck

 + + +

list −p PROGRAM_NAME +[−t list-type] [−a] +[−b]

 +
+ + +

ck

 + + +

list programs +[−t list-type] [−a] +[−b]

 +
+ + +

ck

 + + +

list paths +[−t list-type] [−a] +[−b]

 +
+ + +

ck

 + + +

list ckconf

 +
+ + +

ck

 + + +

edit PROGRAM_NAME +[CONFIG_BASENAME]

 +
+ + +

ck

 + + +

search SEARCH_TERM

 +
+ + +

ck

 + + +

restore −p PROGRAM_NAME

 +
+ + +

ck

 + + +

restore all

 +
+ + +

ck

 + + +

help action

 +

DESCRIPTION @@ -741,17 +928,25 @@ database.

ck uses sqlite to index the configuration files. The init -action by default creates a directory named .ck -under $HOME in witch the ckrc and ckdb -files reside. See the FILES section for more -details.

+action by default creates a directory in witch the +ckrc and ckdb files reside. See the +FILES section for more details.

+ +

ck will +first search for the configuration in the folder shown by +the $CK_CONFIG environment variable. If it is set it +will use the ckrc and ckdb inside this +directory. Else it wil use $XDG_CONFIG_HOME/ck and if +that is not set as well it will fall back to +$HOME/.ck.

One can have multiple config directories with different configurations each. Using the config or −c option one can set the path in which ck will search for ckrc and -ckdb. See the OPTIONS section for more +ckdb. Using this will ignore any environment +variables. See the OPTIONS section for more details.

OPTIONS @@ -772,8 +967,8 @@ order to work.

DIR, −c DIR

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

+ckdb and ckrc residing in +DIR.

−−version, version

@@ -795,320 +990,580 @@ section above.

Each action takes a number of arguments and flags.

-

Initialize -ck
+ +

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

+directory paths to it.
+USAGE

+ + + + + + + + +
-

USAGE

+

ck

 -

ck init -VERSION_CONTROL_DIR SECRET_DIR

+

init VERSION_CONTROL_DIR SECRET_DIR

 +
-

ALIASES

+

ALIASES

init, i, −i

+

ARGUMENTS

-

ARGUMENTS

+ + + + + + + + + + + +
-

VERSION_CONTROL_DIR

-

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

+

VERSION_CONTROL_DIR

 -

SECRET_DIR

+

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

-

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

+

SECRET_DIR

 -

EXAMPLES

-

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

+

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

-

Add -config
+

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.

+will open the primary config by default.
+USAGE

+ + + + + + + +
-

USAGE

-

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

+

ck

 -

ALIASES

+

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

 +
+ +

ALIASES

add, a, −a

+

ARGUMENTS

+ + + + + + + + + + + + +
+ + +

PROGRAM_NAME

 + + +

The name of the program the config belongs +at.

-

ARGUMENTS

-

PROGRAM_NAME

+

CONFIG_PATH

 -

The name of the program -the config belongs at.

+

Path to the config. Can be relative.

-

CONFIG_PATH

+

FLAGS

-

Path to the config. Can -be relative.

+ + + + + + + + + + + +
-

FLAGS

+

−s

 -

−s

-

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

+

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

-

−p

+

−p

 -

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

+

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

-

EXAMPLES

+

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

+
# 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 +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.

+It is up to the user to handle it.
+USAGE

+ + + + + + + + +
-

USAGE

+

ck

 -

ck delete -PROGRAM_NAME|{−c CONFIG_PATH}

+

delete PROGRAM_NAME +[CONFIG_BASENAME]

 +
-

ALIASES

+

ALIASES

delete, del, d, −d

+

ARGUMENTS

-

ARGUMENTS

+ + + + + + + + + + + +
-

PROGRAM_NAME

-

Delete the program and -all it’s configs.

+

PROGRAM_NAME

 -

−c CONFIG_PATH

+

Delete the program and all it’s +configs.

-

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

+

CONFIG_BASENAME

 -

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

-

List -
-List programs, configs and ck configuration values.

+

The basename of the config file to be deleted. It +has to follow the PROGRAM_NAME.

+ +

EXAMPLES

+ +
$ ck delete emacs
+$ ck del emacs init.el
+ + +

LIST +VALUES
+List programs, configs and ck configuration values.
+USAGE

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +

ck

 + + +

list tree [−a] [−b]

 +
+ + +

ck

 + + +

list −p PROGRAM_NAME +[−t list-type] [−a] +[−b]

 +
+ + +

ck

 + + +

list programs +[−t list-type] [−a] +[−b]

 +
+ + +

ck

 + + +

list paths +[−t list-type] [−a] +[−b]

 +
-

USAGE

+

ck

 -

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

+

list ckconf

 +
-

ALIASES

+

ALIASES

list, ls, l, -ls, −l

+

ARGUMENTS

-

ARGUMENTS

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
-

tree

-

List programs with their -configs in a tree like structure.

+

tree

 -

paths

+

List programs with their configs in a tree +like structure.

-

List all the config -paths ck keeps track of.

+

paths

 -

programs

-

List all the programs ck -keeps track of.

+

List all the config paths ck keeps track +of.

-

−c PROGRAM_NAME

+

programs

 -

List all the configs of -PROGRAM_NAME.

+

List all the programs ck keeps track of.

-

ckconf

-

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

+

−c PROGRAM_NAME

 -

FLAGS

+

List all the configs of PROGRAM_NAME.

-

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

+

ckconf

 -

−a

+

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

-

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.

+

FLAGS

+ + + + + + + + + + + + + + + + +
-

−b

-

Print the config -basename instead of the full path.

+

−t type

 -

EXAMPLES

+

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.

-

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

-

Edit -configs
+

−a

 + + +

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

+ + +

−b

 + + +

Print the config basename instead of the full +path.

+ +

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.

+ambiguity, a list of possible configs will be shown. +
+USAGE

+ + + + + + + + +
-

USAGE

+

ck

 -

ck edit -PROGRAM_NAME [CONFIG_BASENAME]

+

edit PROGRAM_NAME +[CONFIG_BASENAME]

 +
-

ALIASES

+

ALIASES

edit, e, −e

+

ARGUMENTS

-

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.

+

PROGRAM_NAME

 -

CONFIG_BASENAME

+

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.

-

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.

+

CONFIG_BASENAME

 -

EXAMPLES

-

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

+

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

-

Search -configs
+

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"

+

$ 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

-

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

+ + + + + + + +
-

USAGE

+

ck

 -

ck search -SEARCH_TERM

+

search SEARCH_TERM

 +
-

ALIASES

+

ALIASES

search, grep, s, −s

+

ARGUMENTS

-

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

+

SEARCH_TERM

 -

EXAMPLES

+

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

-

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

+

EXAMPLES

-

Restore -configs
+

$ ck search "search term"
+$ ck search "\(require"
+ + +

RESTORE +CONFIGS
Given a working ck instance (ckdb + ckrc + directories in ckrc with configs), restore shall recreate the @@ -1143,70 +1598,130 @@ 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. The user will have to take care -of the already created links, if that’s the case.

+of the already created links, if that’s the case. +
+USAGE

+ + + + + + + + + + + + + + +
+ + +

ck

 + + +

restore −p PROGRAM_NAME

 +
-

USAGE

+

ck

 -

ck restore -PROGRAM_NAME|all

+

restore all

 +
-

ALIASES

+

ALIASES

restore, r, −r

+

ARGUMENTS

-

ARGUMENTS

+ + + + + + + + + + + +
-

PROGRAM_NAME

-

The name of the program -to be restored.

+

PROGRAM_NAME

 -

all

-

Restore all programs ck -keeps track of.

+

The name of the program to be restored.

-

EXAMPLES

+

all

 -

$ ck restore all
-$ ck restore -p emacs

-

Get help +

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.

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

+ + + + + + + + +
-

USAGE

+

ck

 -

ck help -action

+

help action

 +
-

ALIASES

+

ALIASES

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

+

ARGUMENTS

+ + + + + + + +
+ -

ARGUMENTS

+

action

 -

action

-

Any action alias you -wish to get help for.

+

Any action alias you wish to get help for.

+

EXAMPLES

-

EXAMPLES

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

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

EXIT STATUS @@ -1223,9 +1738,10 @@ otherwise

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

+ck will store it’s files in $CK_CONFIG +> $XDG_CONFIG_HOME/ck > $HOME/.ck. Using +the −c|−−config one can +change this.

ck generated files
@@ -1285,7 +1801,7 @@ flags: @CMAKE_C_FLAGS@

-

Created: 2018-10-29 Mon 17:20

+

Created: 2018-11-14 Wed 16:42

Validate

-- cgit v1.2.3