1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
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.
|
