[gentoo-soc] Re: Configuration managment system

[Jonas Bernoulli]

This example shows how to use a vcs with confsink and how cfs is a
wrapper around that vcs. If you are used to git then you should
understand the output of the commands easily. If not then it might be
a bit harder to understand. But please also note the options that can
be used to configure confsink. You will be able to configure cfs to
show output more understandable to people not accustomed to the
underlying vcs. Of course when using the vcs directly this won't have
an effect.

So please read this and try to understand. To set you in the right
mood I would like to mention upfront the most important thing to
noticed: Beyond 'cfs focus' you do not need to use cfs at all at least
for all operations that the vcs already supports.

--------------------

$ cfs --help
usage: cfs COMMAND [--package PACKAGE] [ARGS]

The most commonly used cfs commands are:
   ls-files
   status
   diff
   ...

The most commonly used cfs commands for experts are:
   focus     Focus on a particular package/branch or the master branch.
   ...

$ cat /etc/confsink/cfs.conf
# underlying_vcs sets the underlying vcs.  Note that this has to be set
# before cfs and emerge are run for the first time after setting
# FEATURES="confsink" in /etc/make.conf.  It is possible to switch the
# underlying vcs as described in the documentation but this is more
# complicated than just changing the value here.
# default: underlying_vcs=git
#
underlying_vcs=git

# If you are accustomed to the underlying vcs then you should set this
# to true, otherwise it might be better to keep the default of false
# making it easier to understan cfs output.
# default: porceclain_recembles_underlying_vcs=false
#
porceclain_recembles_underlying_vcs=true

# enable_focus is dangerous because it makes 'git clean -fd', act like
# 'rm -rf /'.
# default: enable_focus=false
#
enable_focus=true

# disable_dangerous will prevent dangerous command of the underlying
# commands, like for example 'git clean -fd'.  This is only relevant if
# enable_focus is true.
# default: disable_dangerous=true
disable_dangerous=true

# expert_mode causes the cfs commands to be behave exactly like the
# underlying vcs. If it is not enabled then cfs features different
# commands and the options of some commands have been simplified.
# default: expert_mode=false
expert_mode=true
...

$ cfs package
* overall-configuration
  app-misc/foo
  app-misc/bar
  ...

$ cfs package -v
* overall-configuration
  app-misc/foo
  * live
    vanilla
    experiment
    from-another-user
  app-misc/bar
  * live
    vanilla
  app-misc/baz
  * live
    vanilla
  ...

$ cfs focus -v app-misc/foo
# You are using the git backend.
# Running these commands:
#   export GIT_DIR=/var/confsink
#   export GIT_WORK_TREE=/
#   mv $GIT_DIR/index.d/$package $GIT_DIR/index
#   git symbolic-ref HEAD refs/heads/live/$package
Switched to package "app-misc/foo" branch "live"
# Warning:
#   All git commands in this console will now operate on this package/branch.
#   Don't do this 'git clean -fd', it's like 'rm -rf /'.

[cfs: app-misc/foo/live] $ cfs package
  app-misc/foo
* * live
    vanilla
    experiment
    from-another-user
  app-misc/bar
  app-misc/baz
  ...

[cfs: app-misc/foo/live] $ git ls-files
/etc/foo.conf
/etc/foo-extras.conf

[cfs: app-misc/foo/live] $ cfs focus
# Unfocus. git now operates as normal.

[cfs: app-misc/foo/live] $ git clean -fdx
fatal: operation not permitted, it's considered to be to dangerous.
# Woow take it easy!
# This would wip your system much like 'rm -rf /'.
# Please read the confsink documentation.

$ cfs ls-files --package app-misc/foo
/etc/foo.conf
/etc/foo-extras.conf

$ cfs ls-files
error: no package/branch is currently focused

$ git ls-files
fatal: Not a git repository (or any of the parent directories): .git

$ cfs status
# Packages changed but not updated:
#
#      app-misc/xxx
#      app-misc/yyy
#
# Untracked packages with config protected files:
#
#      app-misc/zzz

$ cfs status --package app-misc/xxx
# Tempory focus on package app-misc/xxx branch live
# Changed but not updated:
#   (use "cfs add --package app-misc/xxx <file>..." to update what
will be committed)
#   (use "cfs checkout --package app-misc/xxx -- <file>..." to discard
changes in working directory)
#
#       modified:   /etc/zzz.conf
no changes added to commit (use "git add" and/or "git commit -a")

$ cfs focus app-misc/xxx
Switched to package "app-misc/xxx" branch "live"
# Warning:
#   All git commands in this console will now operate on this package/branch.
#   Don't do this 'git clean -fd', it's like 'rm -rf /'.

[cfs: app-misc/xxx/live] $ git status
# On branch app-misc/xxx/live
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   /etc/zzz.conf
no changes added to commit (use "git add" and/or "git commit -a")

------------

so this is basically the same:
[1] $ cfs focus PACKAGE; git COMMAND; git focus
[2] $ cfs COMMAND --package PACKAGE COMMAND

git experts would probably prefer [2]. A draw back is that the output
of git will be slightly less informative than that of cfs.

Given the commands demonstrated above one only needs 'cfs focus', but
cfs will also have commands not available in git. For example a
command to show what known repositories contain configuration for a
particular package and if the author provided a description of why he
configured things the way he did also display that. As "described" in
another post there will also be @sets containing related configuration
for multiple packages.

-- Jonas