From dd802fd3ece848d35c8e500e8170924ad90ad64c Mon Sep 17 00:00:00 2001 From: Mike Burns Date: Wed, 31 Jul 2013 08:23:07 -0400 Subject: Re-write the tutorial Thanks to Rebecca Meritz (@rmeritz) for feedback on rcm(7), I have restructured it and re-written the quick start section. Much of the details about the sync algorithm have moved into rcup(1). The new rcm(7) covers a quick start for those with existing directories, including caveats for `install` scripts, dotted filenames, and non-~/.dotfiles directory names; a quick start for those without anything; and motivating sections for "advanced" features like tags, host-specific files, and multiple directories. --- man/rcm.7 | 241 +++++++++++++++++++++++++++---------------------------------- man/rcup.1 | 49 ++++++++++++- 2 files changed, 152 insertions(+), 138 deletions(-) diff --git a/man/rcm.7 b/man/rcm.7 index 0033f0f..cd74d1f 100644 --- a/man/rcm.7 +++ b/man/rcm.7 @@ -33,73 +33,118 @@ 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. +This suite is useful 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 .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 -.Xr mkrc 1 -command to add files to the directory. .Pp -.Dl mkrc .vimrc +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 -You can see the effects of this with +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 QUICK START FOR EXISTING DOTFILES DIRECTORIES +This section is for those who already have an existing dotfiles +directory; this directory is +.Pa ~/.dotfiles ; +the directory only contains rc files; and these rc filenames do not +begin with a period. See the caveats below if this description is close +but not quite right. +.Bl -enum +.It +Dryrun with .Xr lsrc 1 . .Pp .Dl lsrc +.It +Update any symlinks with +.Xr rcup 1 . .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 . +.Dl rcup -v +.It +Add new rc files with +.Xr mkrc 1 . .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 -.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 +.Dl mkrc ~/.tigrc +.El +.Ss CAVEAT: EXISTING INSTALL SCRIPTS +Many existing dotfile directories have scripts named +.Pa install +or +.Pa Makefile +in the directory 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 +.Dl rm -f install Rakefile Makefile install.sh +.Ss CAVEAT: DOTTED FILENAMES IN DOTFILES DIRECTORY +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. +.Pp +.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \; +.Ss CAVEAT: DOTFILES DIRECTORY NOT IN Pa ~/.dotfiles +This all assumes that your dotfiles directory is +.Pa ~/.dotfiles . +If it is elsewhere and you do not want to move it you can use the +.Fl d Ar DIR +option to +.Xr rcup 1 +or modify +.Ev DOTFILES_DIRS +in +.Xr rcrc 5 . +.Pp +.Dl rcup -d configs -v +. +.Sh QUICK START FOR BLANK DOTFILES DIRECTORIES +This section is for those who dot not have an existing dotfiles +directory and whose dotfiles and normal and just as they were created. +.Bl -enum +.It +Add your rc files to a dotfiles directory with +.Xr mkrc 1 . +.Pp +.Dl mkrc .zshrc .gitconfig .tigrc +.It +Synchronize your home directory with .Xr rcup 1 -command. .Pp .Dl rcup -v +.El .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 +This will give you a directory named +.Pa ~/.dotfiles +with your dotfiles in it. Your original dotfiles will be symlinks into +this directory. For example, +.Pa ~/.zshrc +will be a symlink to +.Pa ~/.dotfiles/zshrc . +. +.Sh TAGGED DOTFILES +This suite becomes more powerful when you share your dotfiles directory +between computers, either because multiple people share the same +directory or because you have mutliple computers. +.Pp +If you share the dotfiles directory between people, you may end up with +some irrelevant or even incorrect rc files. For example, you may have a .Pa .zshrc while your other contributor has a .Pa .bashrc . @@ -113,7 +158,7 @@ making a .Pa tag-zsh directory and moving the .Pa .zshrc -into it. +file into it. .Pp .Dl mkrc -t zsh .zshrc .Pp @@ -129,14 +174,15 @@ you can pass the option to include the tags you want. This can also be set in the .Xr rcrc 5 -configuration file, as hinted at above. +configuration file with the +.Ev TAGS +variable. .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 +. +.Sh MULTIPLE DOTFILE DIRECTORIES +Another common situation is combining multiple dotfiles directories that +people have shared with you. For this we have the .Fl d flag or the .Ev DOTFILES_DIRS @@ -151,7 +197,8 @@ will use the first result, not the last; that is, .Pa .dotfiles/vimrc will take precedence over .Pa marriage-dotfiles/vimrc . -.Pp +. +.Sh HOST-SPECIFIC DOTFILES In a similar use case to tags you can also have host-specific files marked. This will go by the hostname. The .Xr rcrc 5 @@ -161,81 +208,7 @@ file is a popular candidate for a host-specific file. .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 -.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, -.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, -.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. -.It -Steps (1) and (2) are applied to tag-specific files. -.El -.Pp -Two alternative conventions in dotfile directories can cause issue with -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. -.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 -.Xr lsrc 1 -command. This shows all the symlinks that the suite intends -to maintain. -.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 FILES .Pa ~/.dotfiles .Pa ~/.rcrc diff --git a/man/rcup.1 b/man/rcup.1 index 5f835f0..b4feca4 100644 --- a/man/rcup.1 +++ b/man/rcup.1 @@ -51,8 +51,8 @@ directories. Two meta files are supported: host-specific files and tagged files. .Pp Host-specific files go in a directory named for the host, prefixed with -.Pa host- -\&. For example, +.Pa host- . +For example, .Pa .dotfiles/host-scarlett contains files specific to the computer with hostname .Pa scarlett @@ -61,12 +61,53 @@ contains files specific to the computer with hostname \&. .Pp Tagged files go in a directory named for the tag, prefixed with -.Li tag -\&. Files under +.Li tag- . +Therefore, files under .Pa .dotfiles/tag-git are only installed when installing using the .Li git tag. +.Sh ALGORITHM +It is instructive to understand the process +.Nm rcup +uses when synchronizing your rc files: +.Bl -enum +.It +All non-host, non-tag files without a dot prefix are symlinked to the +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, +.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. These are files +under a directory named +.Sm off +.Pa host- Va $HOSTNAME . +.Sm on +.It +Steps (1) and (2) are applied to tag-specific files. These are files +under directories named +.Sm off +.Pa tag- Va $TAG_NAME , +.Sm on +where +.Va $TAG_NAME +is the name of each specified tag in turn, taken from the command line +or from +.Xr rcrc 5 . +.El +. .Sh FILES .Pa ~/.dotfiles .Pa ~/.rcrc -- cgit v1.2.3