[Scummvm-devel] SVN Properties: Keywords & MIME type

[Max Horn]

Hi folks,


I wanted to make you all aware of an important Subversion feature:  
Properties. Properties are meta data that can be associated to any  
file in a SVN repository. Essentially, you can define any properties  
you like, but some have a special meaning that is understood by SVN  
clients and used for various useful purposes.

With this mail, I want to (a) make you all aware of this, (b) urge  
you to make proper use of these and (c) tell you how to mostly  
automate this.

For details, see here <http://svnbook.red-bean.com/en/1.1/ch07s02.html>.

Important properties
====================
But the most important properties are :

* svn:mime-type
   The MIME type of the file. "text/plain" for most text files, "text/ 
*" for various special files -- anything else will be treated as  
binary by SVN!

  Usually, you only will have to know two values (actually, only one  
-- if the MIME type is missing, SVN will assume the file is binary):  
"text/plain" for text files like .cpp, .h, .c, and "application/octet- 
stream" for binary files. For a more complete reference, see <http:// 
www.w3schools.com/media/media_mimeref.asp>

* svn:eol-style
    -> Used for text files, indicates with which line ends the file  
shall be checked out. Typical "native", so it uses whatever your  
system uses. The other possible values are CR, LF and CRLF for the  
corresponding line style.

* svn:keywords
   Normally, Subversion will *not* expand keywords like $URL$ and $Id 
$. This is intentionally. If you want keywords to be expanded, you  
have to tell SVN which ones it should expand. For ScummVM, we usually  
set this to "Date Rev Author URL Id"

* svn:ignore
   The successor of the .cvsignore files. Essentially, has the same  
format (i.e. multiple lines, each line is a pattern for filenames SVN  
should ignore).
   Note: you can also add your own list. In my Subversion client  
config file (see the last section of this mail for details!), there  
is a "global-ignores" field where you can ignore more files...


How to manipulate them
======================
If you are using a GUI SVN client, there should be some nice dialog  
to edit these, maybe activate by a context menu or so. If you are  
using the command line client, the most important commands are:
   svn propset PROP VALUE  FILES...
So for example
   svn propset svn:keywords  "Date Rev Author URL Id" backends/x11/x11.h

To delete a property, use "propdel". To get a list of all currently  
set properties use
   svn proplist -v FILE

The client has a nice built-in help function which gives many more  
examples. Just use
   svn help propset
   svn help propget
   svn help propdel
   svn help propedit
   svn help proplist

Or even better, read up in the SVN book (http://svnbook.red- 
bean.com) :-)


How to automate them
====================
So, when you add a new file, it has no properties set. Makes it easy  
to forget them... which is why Subversion lets you set default  
properties for new files! If you are using a Unix style system, take  
a look at ~/.subversion/config. For Win32, it seems the proper  
location is < C:\Documents and Settings\ %USERID% \Application Data 
\Subversion\config>, but I can't verify this.

Anyway, in this text file, make sure that
  enable-auto-props = yes
is present and not commented out. Then, in the [auto-props] section  
(in my case it's near the end of the file), you can add lines like  
the following:

*.gif = svn:mime-type=image/gif
*.jpg = svn:mime-type=image/jpeg
*.pdf = svn:mime-type=application/pdf
*.png = svn:mime-type=image/png
*.c = svn:mime-type=text/plain;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"
*.cpp = svn:mime-type=text/plain;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"
*.css = svn:mime-type=text/css;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"
*.h = svn:mime-type=text/plain;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"
*.htm = svn:mime-type=text/html;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"
*.html = svn:mime-type=text/html;svn:eol- 
style=native;svn:keywords="Date Rev Author URL Id"


-> this way, the right MIME type, EOL style and keyword expansion  
flags will be set automatically when you add a file matching one of  
these patterns via "svn add" (or your graphical Subversion client).  
Works nicely :-)


The config file also allows you to specify a list of filenames that  
should be ignore. On my config file, I have this:

global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store  
lib*.a


So it never bothers me about any file matching one of those  
patterns. :-)

MIME type enforced
==================
Since some files have been checked in by now which are missing all  
properties, I now have changed the Subversion config to enforce MIME  
types. What that means is that if you try to add a file w/o having  
set a svn:mime-type, it'll refuse to let you do that. If that  
happens, just add the proper svn:mime-type (and keywords, and eol- 
style, if applicable!), or, even better, update your SVN config file  
so that it happens automatically next time around :-).


Closing words
=============
If you have any questions about this, feel free to ask. But of  
course, there is also the SVN book, the SVN FAQ, IRC channel #svn  
(next to #scummvm), and many other excellent sources on the net), too!


Cheers,
Max