Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RCM(7)		   FreeBSD Miscellaneous Information Manual		RCM(7)

NAME
     rcm -- dotfile management

SYNOPSIS
     lsrc
     mkrc
     rcdn
     rcup

DESCRIPTION
     The rcm suite of tools is for managing dotfiles directories. This is a
     directory containing all the .*rc files in	your home directory (.zshrc,
     .vimrc, and so on).  These	files have gone	by many	names in history, such
     as	"rc files" because they	typically end in rc or "dotfiles" because they
     begin with	a period.

     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.

     This guide	serves as a tutorial motivating	the suite. For a list of quick
     reference documentation see the SEE ALSO section below.

QUICK START FOR	EXISTING DOTFILES DIRECTORIES
     This section is for those who already have	an existing dotfiles direc-
     tory; this	directory is ~/.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.

     1.	  Dry run with lsrc(1).	 Look for anything unexpected in here, such as
	  ~/.install or	~/.Makefile, or	an empty list of dotfiles.

		lsrc

     2.	  Update any symlinks with rcup(1).  This is likely to do nothing,
	  since	your dotfiles already exist.

		rcup -v

     3.	  When necessary, add new rc files to the dotfiles directory with
	  mkrc(1).

		mkrc ~/.tigrc

	  In the other direction, you can use rcup(1) to create	the symlinks
	  from ~/.dotfiles to your home	directory.

		rcup tigrc

   COMMON PROBLEM: EXISTING INSTALL SCRIPTS
     Many existing dotfile directories have scripts named install or Makefile
     in	the directory. This will cause a ~/.install or ~/.Makefile symlink to
     be	created	in your	home directory.	Use an exclusion pattern to ignore
     these.

	   rcup	-x install -x Rakefile -x Makefile -x install.sh

   COMMON PROBLEM: DOTTED FILENAMES IN DOTFILES	DIRECTORY
     A less common situation is	for all	the filenames in your dotfiles direc-
     tory 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	com-
     mand like the following.

	   find	~/.dotfiles -name '.*' -exec echo mv {}	`echo {} | sed
	   's/.//'` ;

     Note that this will break any existing symlinks. Those can	be safely re-
     moved using the rcdn(1) command.

	   rcdn	-v

   COMMON PROBLEM: DOTFILES DIRECTORY NOT IN ~/.dotfiles
     This all assumes that your	dotfiles directory is ~/.dotfiles.  If it is
     elsewhere and you do not want to move it you can use the -d DIR option to
     rcup(1) or	modify DOTFILES_DIRS in	rcrc(5).

	   rcup	-d configs -v

   COMMON PROBLEM: CONFIGURATION FILES/DIRECTORIES WITHOUT DOTS
     By	default, the rcm suite will prefix every file and directory it manages
     with a dot. If that is not	desired, for example in	the case of ~/bin or
     ~/texmf, you can add that file or directory to UNDOTTED in	rcrc(5)	or use
     the -U option. For	example:

	   mkrc	-U bin

QUICK START FOR	EMPTY DOTFILES DIRECTORIES
     This section is for those who do not have an existing dotfiles directory
     and whose dotfiles	are standard.

     1.	  Add your rc files to a dotfiles directory with mkrc(1).

		mkrc .zshrc .gitconfig .tigrc

     2.	  Synchronize your home	directory with rcup(1)

		rcup -v

     This will give you	a directory named ~/.dotfiles with your	dotfiles in
     it. Your original dotfiles	will be	symlinks into this directory. For ex-
     ample, ~/.zshrc will be a symlink to ~/.dotfiles/zshrc.

TAGGED DOTFILES
     This suite	becomes	more powerful if you share your	dotfiles directory be-
     tween computers, either because multiple people share the same directory
     or	because	you have multiple computers.

     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
     .zshrc while your other contributor has a .bashrc.	 This situation	can be
     handled with tags.

     1.	  A tag	is a directory under the dotfiles directory that starts	with
	  the letters tag-.  We	can handle the competing shell example by mak-
	  ing a	tag-zsh	directory and moving the .zshrc	file into it using
	  mkrc(1) and passing the -t option.

		mkrc -t	zsh .zshrc

     2.	  When updating	with rcup(1) you can pass the -t option	to include the
	  tags you want. This can also be set in the rcrc(5) configuration
	  file with the	TAGS variable.

		rcup -t	zsh

MULTIPLE DOTFILE DIRECTORIES
     Another common situation is combining multiple dotfiles directories that
     people have shared	with you. For this we have the -d flag or the
     DOTFILES_DIRS option in .rcrc.

     The following rcup	invocation will	go in sequence through the three dot-
     files directories,	updating any symlinks as needed. Any overlapping rc
     files will	use the	first result, not the last; that is, .dotfiles/vimrc
     will take precedence over marriage-dotfiles/vimrc.

	   rcup	-d .dotfiles -d	marriage-dotfiles -d thoughtbot-dotfiles

     An	exclusion pattern can be tied to a specific dotfiles directory.

	   rcup	-d .dotfiles -d	work-dotfiles -x 'work-dotfiles:powrc'

HOST-SPECIFIC DOTFILES
     You can also mark host-specific files. This will go by the	hostname. The
     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.

	   mkrc	-o .rcrc

     If	your hostname is difficult to compute, or you otherwise	want to	use a
     different hostname, you can use the -B flag.

	   mkrc	-B eggplant .rcrc

     macOS users should	see the	BUGS section for more details.

STANDALONE INSTALLATION	SCRIPT
     The rcup(1) tool can be used to generate a	portable shell script.	In-
     stead of running a	command	such as	ln(1) or rm(1),	it will	print the com-
     mand to stdout.  This is controlled with the -g flag.  Note that this
     will generate a script to create an exact replica of the synchronization,
     including tags, host-specific files, and dotfiles directories.

	   env RCRC=/dev/null rcup -B 0	-g > install.sh

     Using the above command, you can now run install.sh to install (or	re-in-
     stall) your rc files.  The	install.sh script can be stored	in your	dot-
     files directory, copied between computers,	and so on.

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.

     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 dot-
     files, too.

FILES
     ~/.dotfiles ~/.rcrc

SEE ALSO
     lsrc(1), mkrc(1), rcdn(1),	rcup(1), rcrc(5)

AUTHORS
     rcm is maintained by Mike Burns <mburns@thoughtbot.com> and thoughtbot:
     http://thoughtbot.se

BUGS
     For macOS systems,	we strongly encourage the use of the HOSTNAME variable
     in	your rcrc(5).  We use the hostname(1) program to determine the unique
     identifier	for the	host. This program is not specified by POSIX and can
     vary by system. On	macOS, the hostname is unpredictable, and can even
     change as part of the DHCP	handshake.

CONTRIBUTORS
     Alan Yee <alyee@ucsd.edu>
     Andrei Dziahel <develop7@develop7.info>
     Anton Ilin	<anton@ilin.dn.ua>
     Ben Stephens <BKStephens@outlook.com>
     Ben Turrubiates <ben@turrubiat.es>
     Blake Williams <blake@blakewilliams.me>
     Caleb Land	<caleb@land.fm>
     Carl van Tonder <carl@supervacuo.com>
     Casey Rodarmor <casey@rodarmor.com>
     Christian HoIltje <docwhat@gerf.org>
     Christian HA<paragraph>ltje <docwhat@gerf.org>
     Christopher Koch <ckoch@cs.nmt.edu>
     Dan Croak <dan@thoughtbot.com>
     Daniel Watson <dwatson@thig.com>
     David Alexander <davidpaulalexander@gmail.com>
     Devraj Mehta <devm33@gmail.com>
     Edd Salkield <edd@salkield.uk>
     Eric Collins <eric@tabfugni.cc>
     Florian Tham <fgtham@gmail.com>
     George Brocklehurst <george@thoughtbot.com>
     Graham Bennett <graham@simulcra.org>
     Jarkko KniivilAx <jkniiv@gmail.com>
     Jason Daniel Augustine Gilliland <jdagilliland@gmail.com>
     Javier LA^3pez <linux.kitten@gmail.com>
     Joe Ferris	<jferris@thoughtbot.com>
     John Axel Eriksson	<john@insane.se>
     Jordan Eldredge <jordaneldredge@gmail.com>
     Leonardo Brondani Schenkel	<leonardo@schenkel.net>
     Martin Frost <frost@ceri.se>
     Mat M <matm@gmx.fr>
     Matthew Horan <matt@matthoran.com>
     Melissa Xie <melissa@thoughtbot.com>
     Michael Reed <supertron421@gmail.com>
     Mike Burns	<mburns@thoughtbot.com>
     Mike Burns	and Eric Collins <mburns@thoughtbot.com>
     Nick Novitski <github@nicknovitski.com>
     Pablo Olmos de Aguilera Corradini <pablo@glatelier.org>
     Patrick Brisbin <pat@thoughtbot.com>
     Rafael Santos <formigarafa@gmail.com>
     Rebecca Meritz <rebecca@meritz.com>
     Roberto Pedroso <roberto@rpedroso.com>
     Scott Stevenson <scott@stevenson.io>
     Stephen <stephengroat@users.noreply.github.com>
     Teo Ljungberg <teo@teoljungberg.com>
     Tyson Gach	<tyson@tysongach.com>
     Vlad GURDIGA <gurdiga@gmail.com>
     Yota Toyama <raviqqe@gmail.com>
     Zach Latta	<zach@zachlatta.com>
     kajisha <kajisha@gmail.com>
     maxice8 <thinkabit.ukim@gmail.com>
     subpop <subpop@users.noreply.github.com>
     wplatter-cb <39812934+wplatter-cb@users.noreply.github.com>

FreeBSD	13.0			 July 28, 2013			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | QUICK START FOR EXISTING DOTFILES DIRECTORIES | QUICK START FOR EMPTY DOTFILES DIRECTORIES | TAGGED DOTFILES | MULTIPLE DOTFILE DIRECTORIES | HOST-SPECIFIC DOTFILES | STANDALONE INSTALLATION SCRIPT | RATIONALE | FILES | SEE ALSO | AUTHORS | BUGS | CONTRIBUTORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rcm&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help