.TH MCM "1" "January 2016" "mcm" "User Commands"
.SH NAME
mcm \- Machine Configuration Manager
.SH SYNOPSIS
.B mcm
[\fIOPTION\fR..]
[\fISTARTINGPOINT\fR..]
[\fIOPTION\fR..]
.SH DESCRIPTION
.PP
Configure the specified files and directories
(both file/directory contents and permissions).
Changes to be made (if any) are displayed before they are enacted.
.PP
Machine Configuration Manager can be used to maintain directories,
configuration files and to build scripts in a declarative way.
MCM is designed such that it is easy for its inputs and outputs to be reviewed and audited.
.TP
STARTINGPOINT
starting point (default = "Go.<lowercase_hostname>").
The starting point may be provided partially.  E.g. ".blue" would result in the
starting point "Go.blue" being used; similarly "MyUserConfigs." would result in
"MyUserConfigs.<lowercase_hostname>" being used.
Multiple starting points may be provided, though it only really makes sense to
provide multiple starting points together with the options
\fB\-\-parse\-only\fR or \fB\-\-compile-to\fR.
.SH OPTIONS
.TP
\fB\-V\fR, \fB\-\-version\fR
show version
.TP
\fB\-P\fR \fIPATH\fR, \fB\-\-config\-path\fR=\fIPATH\fR
colon\-separated list of directories holding configs (default = ".")
.TP
\fB\-r\fR \fIDIRECTORY\fR, \fB\-\-root\fR=\fIDIRECTORY\fR
path to manage (default = "./build")
.TP
\fB\-f\fR \fIno\fR|\fIprompt\fR|\fIifnew\fR|\fIyes\fR|\fIpromptunlessonlyadditions\fR, \fB\-\-fix\fR=\fIno\fR|\fIprompt\fR|\fIifnew\fR|\fIyes\fR|\fIpromptunlessonlyadditions\fR
whether to enact the changes (default = \fIprompt\fR).
\fIno\fR and \fIyes\fR result in the changes being only displayed or unconditionally enacted respectively.
\fIifnew\fR causes the changes to be made if the root directory does not exist.
\fIprompt\fR asks the user whether to enact the changes,
\fIpromptunlessonlyadditions\fR automatically enacts the changes if the changes would only result in the addition of new files and/or directories, otherwise prompts the user.
.TP
\fB\-d\fR, \fB\-\-diff\fR
display differences (requires 'diff')
.TP
\fB\-\-parse\-only\fR
parse configuration(s) only
.TP
\fB\-c\fR \fIDIRECTORY\fR, \fB\-\-compile\-to\fR=\fIDIRECTORY\fR
compile (each provided starting point) to a single (but separate) file.
Compiled files can then, for example, be sent to destination hosts for implementation.
.TP
\fB\-\-stdin\fR
read (initial) config from stdin
.TP
\fB\-\-error\-on\-leftover\-fragments\fR
complain if there are fragments without corresponding files

.SH EXIT STATUS
.TP
0
if OK,
.TP
1
when errors are encountered in either reading the config files or implementing
the changes,
.TP
2
if \fB--fix\fR=\fIifnew\fR but the root path to manage already exists,
.TP
3
if \fB--fix\fR=\fIprompt\fR or \fB--fix\fR=\fIpromptunlessonlyadditions\fR and the changes are not enacted (e.g. "N" is entered).
.SH NOTES
The use of aliases/functions (e.g. in ~/.bashrc) is recommended for frequently used invocations.
For example:
.IP
alias mcmroot='sudo mcm -r / -P ~/mcm'
.br
alias mcmhome='mcm -r / -P ~/mcm MyUserConfigs.'
.PP
Or if using the grc colouriser:
.IP
alias mcmroot='grc sudo mcm -r / -P ~/mcm'
.br
alias mcmhome='grc mcm -r / -P ~/mcm MyUserConfigs.'
.PP
You might also like to create an alias along the lines of the following,
where mcmuserscripts and mcmrootscripts run any Machine Configuration Manager-generated scripts:
.IP
alias mcmall='mcmuser && mcmuserscripts; mcmroot && mcmrootscripts'
.PP
.SH FILES
None but those within directories specified with \fB\-\-config\-path\fR.
.SH ENVIRONMENT
.TP
\fIPATH\fR
$PATH can be altered to change the version of diff invoked when the \fB-d\fR, \fB--diff\fR option is provided.
.SH EXAMPLES
Starting with the define "mystart" in the file "Go.mcm" in the current
directory (with the MCM Package of "Go"),
show what changes would be made to
the root ./build and then prompt whether to enact them:
.IP
mcm .mystart
.PP
Starting with the define "<lowercase_hostname>" in the file "MyUserConfigs.mcm" in
the current directory (with the MCM Package of "MyUserConfigs"),
show what changes would be made to the root ~/ and then prompt whether to enact
them:
.IP
mcm -r ~/ MyUserConfigs.
.PP
Test a long list of starting points (e.g. that a change made for one of them has not broken any others):
.IP
mcm --parse-only --error-on-leftover-fragments .oak .beech .birch .maple \\
    MyUserConfigs.oak MyUserConfigs.beech MyUserConfigs.birch MyUserConfigs.maple \\
    LiveCD.basic LiveCD.X11 LiveCD.friends \\
    DebianInstaller.basic DebianInstaller.home DebianInstaller.work DebianInstaller.friends \\
    Deb.basic Deb.mypackage \\
    Website.main Website.photos \\
    RaspberryInstallation.simple RaspberryInstallation.maple RaspberryInstallation.demo
.PP
Compile the starting points (Go).maple and MyUserConfigs.maple to single files.
The single files can then, for example, be copied to the destination host for
implementation, or compared to other compiled files.
.IP
grc mcm -d -r / -c compiled/ .maple MyUserConfigs.maple

.SH AUTHOR
Written by Anthony Doggett <mcm@interfaces.org.uk>
.SH REPORTING BUGS
Please email the author at the above address, preferably with sufficient information to reproduce the bug.
.SH COPYRIGHT
Copyright (c) 2014-2018 Anthony Doggett
.PP
<http://interfaces.org.uk/mcm>
.SH SEE ALSO
mcm2html(1),
mcmtags(1)