From 6324506f529651c80b3cf35465ed4605cfd86817 Mon Sep 17 00:00:00 2001 From: Mike Burns Date: Sat, 27 Jul 2013 23:15:45 -0400 Subject: Add tutorial-style documentation: rcm(7) Add a manpage with a tutorial, named `rcm`. This covers how to get started from nothing, how to convert an existing dotfiles directory, and why to use suite at all. --- man/Makefile.am | 2 +- man/Makefile.in | 2 +- man/rcm.7 | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ man/rcrc.5 | 2 +- 4 files changed, 174 insertions(+), 3 deletions(-) create mode 100644 man/rcm.7 diff --git a/man/Makefile.am b/man/Makefile.am index 6b6b1b5..766c24c 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1 +1 @@ -man_MANS = lsrc.1 mkrc.1 rcrc.5 rcup.1 +man_MANS = lsrc.1 mkrc.1 rcrc.5 rcup.1 rcm.7 diff --git a/man/Makefile.in b/man/Makefile.in index 07d55cf..a1b10d7 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -169,7 +169,7 @@ target_alias = @target_alias@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ -man_MANS = lsrc.1 mkrc.1 rcrc.5 rcup.1 +man_MANS = lsrc.1 mkrc.1 rcrc.5 rcup.1 rcm.7 all: all-am .SUFFIXES: diff --git a/man/rcm.7 b/man/rcm.7 new file mode 100644 index 0000000..46fb3de --- /dev/null +++ b/man/rcm.7 @@ -0,0 +1,171 @@ +.TH rcm "7" "July 2013" "rcm" + +.SH NAME +rcm \- dotfile management + +.SH DESCRIPTION + +The rcm suite of tools is for managing dotfiles directories. This is a +directory containing all the \fI.*rc\fR files in your home directory +(\fI.zshrc\fR, \fI.vimrc\fR, and so on). These files have gone by many +names in history, such as \fIrc files\fR because they typically end in +\fBrc\fR or \fIdotfiles\fR because they begin with a period. + +This suite is useful, for example, for commiting your rc files to a +central repository to share on GitHub, but it also scales to a more +complex situation such as mutliple source directories shared between +computers with some host-specific or task-specific files. + +This guide serves as a tutorial motivating the suite. For a list of +quick reference documentation see the \fBSEE ALSO\fR section below. + +.SH QUICK START + +If you do not already have a dotfiles directory then we can get started +quickly. Use the \fImkrc\fR\|(1) command to add files to the directory. + +.B mkrc .vimrc + +You can see the effects of this with \fIlsrc\fR\|(1). + +.B lsrc + +The default dotfiles directory is \fB$HOME/.dotfiles\fR\|. The +\fImkrc\fR command will move \fB.vimrc\fR to \fB.dotfiles/vimrc\fR, then +symlink \fB.vimrc\fR to \fBdotfiles/vimrc\fR\|. + +This suite becomes more powerful when you share your dotfiles directory +between computers, either because mutliple people share the same +directory or because you have mutliple computers. As a quick simulation, +we can create a file in your new \fB.dotfiles\fR directory. + +.B echo TAGS="zsh" > ~/.dotfiles/rcrc + +We can update our home directory to have a new \fB.rcrc\fR file (a +symlink to \fB.dotfiles/rcrc\fR\|) using the \fIrcup\fR\|(1) command. + +.B rcup -v + +We passed the \fB-v\fR option to see in more explicit detail what it +does. All rcm commands take the \fB-v\fR option, and mutliple \fB-v\fR +options can be given to give more explicit detail. + +If you do share the dotfiles directory between people, you may end up +with some irrelevant or even incorrect rc files. For example, you may +have a \fB.zshrc\fR while your other contributor has a \fB.bashrc\fR\|. +This situation can be handled with tags. + +A tag is a directory under the dotfiles directory the starts with the +letters \fBtag-\fR\|. We can handle the competing shell example by +making a \fBtag-zsh\fR directory and moving the \fB.zshrc\fR into it. + +.B mkrc -t zsh .zshrc + +And likewise, your dotfiles partner would do the same for +\fB.bashrc\fR\|. + +.B mkrc -t bash .bashrc + +When updating with \fIrcup\fR you can pass the \fB-t\fR option to +include the tags you want. This can also be set in the \fBrcrc\fR\|(5) +configuration file, as hinted at above. + +.B rcup -t zsh + +The tags are useful for sharing a single dotfiles directory between +competers or people, but another common situation is combining multiple +dotfiles directories that people have shared with you. For this we have +the \fB-d\fR flag or the \fBDOTFILES_DIRS\fR option in \fB.rcrc\fR\|. + +.B rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles + +This rcup invocation will go in sequence through the three dotfiles +directories, updating any symlinks as needed. Any overlapping rc files +will use the first result, not the last; that is, \fB.dotfiles/vimrc\fR +will take precedence over \fBmarriage-dotfiles/vimrc\fR\|. + +In a similar use case to tags you can also have host-specific files +marked. This will go by the hostname. The \fBrcrc\fR\|(5) configuration +file is a popular candidate for a host-specific file. + +.B mkdir .dotfiles/host-`hostname` +.P +.B mv .rcrc .dotfiles/host-`hostname`/rcrc +.P +.B rcup -v + +.SH MIGRATING EXISTING WORKFLOWS + +Many people have existing dotfiles directories, and have been managing +them using custom scripts. The suite of tools in this package should be +able to replace your custom scripts with little effort. + +When converting an existing dotfiles directory you do need some +knowledge of how rcm works and what it expects. Details can be found in +\fIrcup\fR\|(1), but briefly: + +.TP +1 +All non-host, non-tag files without a dot prefix are symlinked to the +dotted filename in your home directory. So, \fB.dotfiles/tigrc\fR is +symlinked to \fB~/.tigrc\fR\|. + +.TP +2 +All non-host, non-tag directories have their structure copied to your +home directory, then a non-dotted symlink is created within. So for +example, \fB.dotfiles/vim/autoload/haskell.vim\fR causes the +\fB~/.vim/autoload\fR directory to be created, then \fBhaskell.vim\fR is +symlinked within. + +.TP +3 +Steps (1) and (2) are applied to host-specific files. + +.TP +4 +Steps (1) and (2) are applied to tag-specific files. + +.PP + +Two alternative conventions in dotfile directories can cause issue with +this. The most common problem is to have a file named \fBinstall\fR or +\fBMakefile\fR in your dotfiles directory. This will cause a +\fB~/.install\fR or \fB~/.Makefile\fR symlink to be created in your home +directory. The best option here is to move that file outside of your +dotfiles directory, or remove it entirely. + +A less common situation is for all the filenames in your dotfiles +directory to be prefixed with a period. These files are skipped by the +rcm suite, and thus would result in nothing happening. The only option +in this case is to rename all the files, for example by using a shell +command like the following. Note that this will break any existing +symlinks. + +.B find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \; + +The easiest way to see what the rcm suite will do is to run the +\fIlsrc\fR\|(1) command. This shows all the symlinks that the suite intends +to maintain. + +Once you are satisfied and ready to try rcm, use the \fIrcup\fR command. + +.SH WHY RCM + +The rcm suite was built as an abstraction over the shell, Ruby, Python, +and make scripts people were writing and sharing. It is intended to run +on any unix system and support the range from simple to complex dotfile +directories. + +As such, this suite is useful as a common base. Through this we can +share tools and develop this further as a first-class entity. It is also +our hope that a common set of tools will encourage others to share their +dotfiles, too. + +.SH SEE ALSO + +\&\fImkrc\fR\|(1), \fIrcup\fR\|(1), \fIlsrc\fR\|(1), \fIrcrc\fR\|(5) + +.SH AUTHOR + +Written by Mike Burns. diff --git a/man/rcrc.5 b/man/rcrc.5 index 6f28e06..2f9e02a 100644 --- a/man/rcrc.5 +++ b/man/rcrc.5 @@ -37,4 +37,4 @@ Written by Mike Burns. .SH SEE ALSO -\&\fImkrc\fR\|(5), \fIrcup\fR\|(1), \fIlsrc\fR\|(1) +\&\fImkrc\fR\|(1), \fIrcup\fR\|(1), \fIlsrc\fR\|(1) -- cgit v1.2.3