diff options
Diffstat (limited to 'man/rcm.7')
| -rw-r--r-- | man/rcm.7 | 313 |
1 files changed, 195 insertions, 118 deletions
@@ -1,171 +1,248 @@ -.TH rcm "7" "July 2013" "rcm" - -.SH NAME -rcm \- dotfile management - -.SH DESCRIPTION - +.Dd July 28, 2013 +.Dt RCM 7 +.Os +.Sh NAME +.Nm rcm +.Nd dotfile management +.Sh SYNOPSIS +.Nm lsrc +.Nm mkrc +.Nm rcup +.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. - +directory containing all the +.Li .*rc +files in your home directory +.Sm off +.Po +.Pa .zshrc , +.Sm on +.Pa .vimrc , +and so on +.Pc . +These files have gone by many +names in history, such as +.Do +rc files +.Dc +because they typically end in +.Li rc +or +.Do +dotfiles +.Dc +because they begin with a period. +.Pp 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. - +.Pp 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 - +quick reference documentation see the +.Sx SEE ALSO +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\|. - +quickly. Use the +.Xr mkrc 1 +command to add files to the directory. +.Pp +.Dl mkrc .vimrc +.Pp +You can see the effects of this with +.Xr lsrc 1 . +.Pp +.Dl lsrc +.Pp +The default dotfiles directory is +.Pa $HOME/.dotfiles . +The +.Xr mkrc 1 +command will move +.Pa .vimrc +to +.Pa .dotfiles/vimrc , +then symlink +.Pa .vimrc +to +.Pa .dotfiles/vimrc . +.Pp 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 +we can create a file in your new +.Pa .dotfiles +directory. +.Pp +.Dl echo TAGS="zsh" > ~/.dotfiles/rcrc +.Pp +We can update our home directory to have a new +.Pa .rcrc +file (a symlink to +.Pa .dotfiles/rcrc ) +using the +.Xr rcup 1 +command. +.Pp +.Dl rcup -v +.Pp +We passed the +.Fl v +option to see in more explicit detail what it +does. All rcm commands take the +.Fl v +option, and mutliple +.Fl v options can be given to give more explicit detail. - +.Pp 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\|. +have a +.Pa .zshrc +while your other contributor has a +.Pa .bashrc . This situation can be handled with tags. - +.Pp 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 - +letters +.Li tag- . +We can handle the competing shell example by +making a +.Pa tag-zsh +directory and moving the +.Pa .zshrc +into it. +.Pp +.Dl mkrc -t zsh .zshrc +.Pp 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) +.Pa .bashrc . +.Pp +.Dl mkrc -t bash .bashrc +.Pp +When updating with +.Xr rcup 1 +you can pass the +.Fl t +option to +include the tags you want. This can also be set in the +.Xr rcrc 5 configuration file, as hinted at above. - -.B rcup -t zsh - +.Pp +.Dl rcup -t zsh +.Pp 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 - +the +.Fl d +flag or the +.Ev DOTFILES_DIRS +option in +.Pa .rcrc . +.Pp +.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles +.Pp 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\|. - +will use the first result, not the last; that is, +.Pa .dotfiles/vimrc +will take precedence over +.Pa marriage-dotfiles/vimrc . +.Pp 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 +marked. This will go by the hostname. The +.Xr rcrc 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 - +.Pp +.Dl mkdir .dotfiles/host-`hostname` +.Dl mv .rcrc .dotfiles/host-`hostname`/rcrc +.Dl rcup -v +.Pp +.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. - +.Pp 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 +.Xr rcup 1 , +but briefly: +.Bl -enum +.It 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 +dotted filename in your home directory. So, +.Pa .dotfiles/tigrc +is +symlinked to +.Pa ~/.tigrc . +.It 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 +example, +.Pa .dotfiles/vim/autoload/haskell.vim +causes the +.Pa ~/.vim/autoload +directory to be created, then +.Pa haskell.vim +is symlinked within. +.It Steps (1) and (2) are applied to host-specific files. - -.TP -4 +.It Steps (1) and (2) are applied to tag-specific files. - -.PP - +.El +.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 +this. The most common problem is to have a file named +.Pa install +or +.Pa Makefile +in your dotfiles directory. This will cause a +.Pa ~/.install +or +.Pa ~/.Makefile +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. - +.Pp 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/\.//'` \; - +.Pp +.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \; +.Pp 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 +.Xr lsrc 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 - +.Pp +Once you are satisfied and ready to try rcm, use the +.Xr rcup 1 +command. +.Pp +.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. - +.Pp 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. +.Sh FILES +.Pa ~/.dotfiles +.Pa ~/.rcrc +.Sh SEE ALSO +.Xr lsrc 1 , +.Xr mkrc 1 , +.Xr rcup 1 , +.Xr rcrc 5 +.Sh AUTHORS +.An "Mike Burns" Aq mike@mike-burns.com |