1. cvsreport.pl (vcv) : Adding & Overlaying

In $LJHOME/bin there's a tool named vcv (“version control views”). This tool, named cvsreport.pl in its original incarnation, manages (among other things) merging together the general files and your site-local files into the live area under $LJHOME. It uses a file named multicvs.conf for mapping instructions, to find out where to place the different files. The cvsreport.pl utility is just a front-end to the vcv tool.

The command you'll need most of the time is:

$ bin/cvsreport.pl -u -c -s

-u is short for --update (the files in the local cvs directory from the external SVN repositories), -c is short for --cvsonly (only copies from the cvs directory back to the live area, not vice-versa) and -s is short for --sync (which means actually do the copying, don't just print out what it would have done, which is the default without -s).

So, say you want to override the provided htdocs/index.bml file. Create the htdocs under $LJHOME/cvs/local and put an index.bml file in it, then run cvsreport.pl -c -s and you are set.

More commonly, you will be adding new files, rather than replacing provided ones. In general, you should never really need to replace files, since you should already be able to change all the text, images, and layout of any given page. Replacing a file would mean duplicating functionality, and that's bad.

One popular strategy with the general code libraries is to look for a similarly named file with -local in it and load that also. That way you inherit all the functionality that is provided, and change only what you want. When general changes, you don't have to update right away… you can change things later if you want, or keep the newly added stuff as it was given to you.