From 6dcd69174d3c0258bf525ee2a7e184b30fad0fd3 Mon Sep 17 00:00:00 2001 From: Mike Burns Date: Wed, 19 Mar 2014 17:44:50 +0100 Subject: Generate the list of contributors from git Instead of requiring contributors to update rcm(7), pull the list of contributors from the git log instead. The `rcm.7` file has been moved to `rcm.7.mustache`. The `autogen.sh` command will write `rcm.7` using autocontrib, a quick script included in this commit. This commit adds a `.mailmap` file, used by git-shortlog(1) to produce correct and useful names and email addresses. An initial `.mailmap` has been added to correct some existing email addresses and duplications. `.mailmap` is documented in [Documentation/mailmap.txt][mailmap] for git. This adds a maintainer dependency on Ruby and the mustache gem. The autocontrib program is spiked out in Ruby due to my familarity with the language, but the choice of templating language (mustache) allows flexibility for switching languages later. This is a dependency requirement only for people who run `autogen.sh` -- maintainers. This adds a maintainer dependency on git. Again, this is only for maintainers, and many (all?) of them need git to get rcm's source anyway. Thanks to Patrick Brisbin and George Brocklehurst for the review. [mailmap]: https://github.com/git/git/blob/6a907786af835ac15962be53f1492f23e044f479/Documentation/mailmap.txt --- man/rcm.7 | 253 ----------------------------------------------------- man/rcm.7.mustache | 246 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 246 insertions(+), 253 deletions(-) delete mode 100644 man/rcm.7 create mode 100644 man/rcm.7.mustache (limited to 'man') diff --git a/man/rcm.7 b/man/rcm.7 deleted file mode 100644 index 71b99f4..0000000 --- a/man/rcm.7 +++ /dev/null @@ -1,253 +0,0 @@ -.Dd July 28, 2013 -.Dt RCM 7 -.Os -.Sh NAME -.Nm rcm -.Nd dotfile management -.Sh SYNOPSIS -.Nm lsrc -.Nm mkrc -.Nm rcdn -.Nm rcup -.Sh DESCRIPTION -The rcm suite of tools is for managing dotfiles directories. This is a -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 committing your rc files to a central repository -to share, but it also scales to a more complex situation such as -multiple 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 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 is not you. -.Bl -enum -.It -Dryrun with -.Xr lsrc 1 . -Look for anything unexpected in here, such as -.Pa ~/.install -or -.Pa ~/.Makefile , -or an empty list of dotfiles. -.Pp -.Dl lsrc -.It -Update any symlinks with -.Xr rcup 1 . -This is likely to do nothing, since your dotfiles already exist. -.Pp -.Dl rcup -v -.It -When necessary, add new rc files with -.Xr mkrc 1 . -.Pp -.Dl mkrc ~/.tigrc -.El -.Ss COMMON PROBLEM: 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. Use an exclusion pattern to ignore these. -.Pp -.Dl rcup -x install -x Rakefile -x Makefile -x install.sh -.Ss COMMON PROBLEM: 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. -.Pp -.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \; -.Pp -Note that this will break any existing symlinks. Those can be safely -removed using the -.Xr rcdn 1 -command. -.Pp -.Dl rcdn -v -.Ss COMMON PROBLEM: 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 EMPTY DOTFILES DIRECTORIES -This section is for those who do not have an existing dotfiles -directory and whose dotfiles are standard. -.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 -.Pp -.Dl rcup -v -.El -.Pp -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 if you share your dotfiles directory -between computers, either because multiple people share the same -directory or because you have multiple 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 . -This situation can be handled with tags. -.Bl -enum -.It -A tag is a directory under the dotfiles directory the starts with the -letters -.Li tag- . -We can handle the competing shell example by -making a -.Pa tag-zsh -directory and moving the -.Pa .zshrc -file into it using -.Xr mkrc 1 -and passing the -.Fl t -option. -.Pp -.Dl mkrc -t zsh .zshrc -.It -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 with the -.Ev TAGS -variable. -.Pp -.Dl rcup -t zsh -.El -. -.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 -option in -.Pa .rcrc . -.Pp -The following 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, -.Pa .dotfiles/vimrc -will take precedence over -.Pa marriage-dotfiles/vimrc . -.Pp -.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles -.Pp -An exclusion pattern can be tied to a specific dotfiles directory. -.Pp -.Dl rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc' -. -.Sh HOST-SPECIFIC DOTFILES -You can also mark host-specific files. This will go by the hostname. The -.Xr rcrc 5 -configuration -file is a popular candidate for a host-specific file, since the tags and -dotfile directories listed in there are often specific to a single -machine. -.Pp -.Dl mkrc -o .rcrc -. -.Sh RATIONALE -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 -.Sh SEE ALSO -.Xr lsrc 1 , -.Xr mkrc 1 , -.Xr rcdn 1 , -.Xr rcup 1 , -.Xr rcrc 5 -.Sh AUTHORS -.Nm -is maintained by -.An "Mike Burns" Aq Mt mburns@thoughtbot.com -and -.Lk http://thoughtbot.se thoughtbot -.Sh CONTIRBUTORS -.An -split -.An "Anton Ilin" Aq Mt anton@ilin.dn.ua -.An "Caleb Land" Aq Mt caleb@land.fm -.An "Dan Croak" Aq Mt dan@thoughtbot.com -.An "Daniel Watson" Aq Mt dbwatson@vectorspace.org -.An "George Brocklehurst" Aq Mt george@thoughtbot.com -.An "Javier López" Aq Mt linux.kitten@gmail.com -.An "Jordan Eldredge" Aq Mt jordaneldredge@gmail.com -.An "Pablo Olmos de Aguilera Corradini" Aq Mt pablo@glatelier.org -.An "Patrick Brisbin" Aq Mt pat@thoughtbot.com -.An "Roberto Pedroso" Aq Mt roberto@rpedroso.com diff --git a/man/rcm.7.mustache b/man/rcm.7.mustache new file mode 100644 index 0000000..8956e5d --- /dev/null +++ b/man/rcm.7.mustache @@ -0,0 +1,246 @@ +.Dd July 28, 2013 +.Dt RCM 7 +.Os +.Sh NAME +.Nm rcm +.Nd dotfile management +.Sh SYNOPSIS +.Nm lsrc +.Nm mkrc +.Nm rcdn +.Nm rcup +.Sh DESCRIPTION +The rcm suite of tools is for managing dotfiles directories. This is a +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 committing your rc files to a central repository +to share, but it also scales to a more complex situation such as +multiple 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 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 is not you. +.Bl -enum +.It +Dryrun with +.Xr lsrc 1 . +Look for anything unexpected in here, such as +.Pa ~/.install +or +.Pa ~/.Makefile , +or an empty list of dotfiles. +.Pp +.Dl lsrc +.It +Update any symlinks with +.Xr rcup 1 . +This is likely to do nothing, since your dotfiles already exist. +.Pp +.Dl rcup -v +.It +When necessary, add new rc files with +.Xr mkrc 1 . +.Pp +.Dl mkrc ~/.tigrc +.El +.Ss COMMON PROBLEM: 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. Use an exclusion pattern to ignore these. +.Pp +.Dl rcup -x install -x Rakefile -x Makefile -x install.sh +.Ss COMMON PROBLEM: 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. +.Pp +.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \; +.Pp +Note that this will break any existing symlinks. Those can be safely +removed using the +.Xr rcdn 1 +command. +.Pp +.Dl rcdn -v +.Ss COMMON PROBLEM: 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 EMPTY DOTFILES DIRECTORIES +This section is for those who do not have an existing dotfiles +directory and whose dotfiles are standard. +.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 +.Pp +.Dl rcup -v +.El +.Pp +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 if you share your dotfiles directory +between computers, either because multiple people share the same +directory or because you have multiple 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 . +This situation can be handled with tags. +.Bl -enum +.It +A tag is a directory under the dotfiles directory the starts with the +letters +.Li tag- . +We can handle the competing shell example by +making a +.Pa tag-zsh +directory and moving the +.Pa .zshrc +file into it using +.Xr mkrc 1 +and passing the +.Fl t +option. +.Pp +.Dl mkrc -t zsh .zshrc +.It +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 with the +.Ev TAGS +variable. +.Pp +.Dl rcup -t zsh +.El +. +.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 +option in +.Pa .rcrc . +.Pp +The following 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, +.Pa .dotfiles/vimrc +will take precedence over +.Pa marriage-dotfiles/vimrc . +.Pp +.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles +.Pp +An exclusion pattern can be tied to a specific dotfiles directory. +.Pp +.Dl rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc' +. +.Sh HOST-SPECIFIC DOTFILES +You can also mark host-specific files. This will go by the hostname. The +.Xr rcrc 5 +configuration +file is a popular candidate for a host-specific file, since the tags and +dotfile directories listed in there are often specific to a single +machine. +.Pp +.Dl mkrc -o .rcrc +. +.Sh RATIONALE +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 +.Sh SEE ALSO +.Xr lsrc 1 , +.Xr mkrc 1 , +.Xr rcdn 1 , +.Xr rcup 1 , +.Xr rcrc 5 +.Sh AUTHORS +.Nm +is maintained by +.An "Mike Burns" Aq Mt mburns@thoughtbot.com +and +.Lk http://thoughtbot.se thoughtbot +.Sh CONTRIBUTORS +.An -split +{{#contributors}} +.An "{{{name}}}" Aq Mt {{{email}}} +{{/contributors}} -- cgit v1.2.3