Subversion repository structure for web applications

If you are coding a lot of web applications, it helps to have a standard directory structure that you start with. That you always know where files should go, etc. This page contains my (current) take on the topic.

These steps assume you already have Subversion set up and working. If it’s on a remote machine, use the appropriate protocol designator (http://svn://, etc.) below where you see file://.

Alternatively, you could just put the directory creation commands into a script and run that script every time you needed to set up a new project. But we should all be using some sort of version control system, now shouldn’t we?

Just copy and paste the commands into a terminal session on your workstation or server, and that should be all you need to do to set this up. You will need to make some changes for your actual repository path and project names, of course. I’m just putting sample stuff in my examples.

Set up your desired directory “skeleton” in a temporary directory. Note that this uses a “shortcut” feature of <code>mkdir</code> that allows you to specify multiple subdirectories at once. The format is important – no spaces after the , etc.

cd ~
mkdir -p skeleton/{branches,tags,trunk/{data,db,doc,util,www/{include/{css,js},media/img}}}

You now have a directory system that looks like this:

/home/user
          /skeleton
                   /data
                   /db
                   /doc
                   /util
                   /www
                       /include
                               /css
                               /js
                       /media
                             /img

This will yield a website structure like this:

[web_root]
          /include
                  /css
                  /js
          /media
                /img

Of course you can add other directories as needed to further organize the website, but this will give you a good beginning, and help keep things organized. You will always know the path to CSS and Javascript files, regardless of where on the site you reference them in your HTML.

  • /data is where any “test” data goes that you need to prepopulate the project. This may not be relevant for the app you are building, so you could leave this one out.
  • /db contains SQL scripts used to create and populate any needed databases and tables. Be sure to add migration or update/upgrade scripts if the schemas change at some point during the project’s lifecycle.
  • /doc is for any and all project documentation. Be sure to paste important emails into text files and stash them in here!
  • /util is where any supporting scripts (Perl, shell, etc.) would go.
  • /www is the root dir for the website content.
  • /www/include is where any included files would go (think PHP’s require and include commands).
  • /www/include/css is where all your CSS files go. You are using CSS, right?
  • /www/include/js is where all Javascript goes. Javascript should be included in your HTML and PHP files via the <script src="...">, not inline.
  • /www/media should be pretty obvious. I like to use subdirectories for each media type to help keep things organized. Almost every project uses at least one image someplace, so I default to creating the /www/media/img directory in the skeleton. Later, if I need video, audio, flash, etc., I would make new subdirectories for them as well.

Once the directories are set up, I put some “marker” files in certain directories as well, which get filled in for the specific project once I start working on it:

cd ~/skeleton/trunk
touch FAQ HISTORY LICENSE README RELEASE-NOTES UPGRADE
touch doc/ABOUT

I also put empty index.html files into the various web directories, to prevent direct access to them when the project is deployed on a live server:

touch www/include/index.html
touch www/include/css/index.html
touch www/include/js/index.html
touch www/media/index.html
touch www/media/img/index.html

Set up a default CSS file (customize per your own experiences, needs, etc.) and stick it in the /include/css directory. See Five Steps to CSS Heaven for more ideas.

cd include/css
touch style.css

echo "/* Design and Code (c) Company Name, Inc. */" >> style.css
echo "html, body { padding: 0; margin: 0; }" >> style.css
echo >> style.css
echo "body {" >> style.css
echo "	font: normal 12px/1.5em sans-serif;" >> style.css
echo "	background: #fff; }" >> style.css
echo >> style.css
echo "/* Headings H1-H6 */" >> style.css
echo "h1 { }" >> style.css
echo >> style.css
echo "h2 { }" >> style.css
echo >> style.css
echo "h3 { }" >> style.css
echo >> style.css
echo "h4 { }" >> style.css
echo >> style.css
echo "h5 { }" >> style.css
echo >> style.css
echo "h6 { }" >> style.css
echo >> style.css
echo "/* Paragraph and Link Styles */" >> style.css
echo "p { }" >> style.css

cd ../..

Note that I use the “echo >>” mechanism rather than an actual file so that you can copy/paste all these commands and it will “just work” – no file editor needed at this stage.

Next, create a new project repository:

svnadmin create --fs-type fsfs /path/to/repos/projectname

Finally, import the directory structure into the project:

svn import ~/skeleton file:///path/to/repos/projectname -m "Initial project 'projectname' setup"

Gives this result:

Adding /home/user/skeleton/trunk
Adding /home/user/skeleton/trunk/HISTORY
Adding /home/user/skeleton/trunk/LICENSE
Adding /home/user/skeleton/trunk/www
Adding /home/user/skeleton/trunk/www/media
Adding /home/user/skeleton/trunk/www/media/index.html
Adding /home/user/skeleton/trunk/www/media/img
Adding /home/user/skeleton/trunk/www/media/img/index.html
Adding /home/user/skeleton/trunk/www/include
Adding /home/user/skeleton/trunk/www/include/css
Adding /home/user/skeleton/trunk/www/include/css/index.html
Adding /home/user/skeleton/trunk/www/include/css/style.css
Adding /home/user/skeleton/trunk/www/include/index.html
Adding /home/user/skeleton/trunk/www/include/js
Adding /home/user/skeleton/trunk/www/include/js/index.html
Adding /home/user/skeleton/trunk/www/index.html
Adding /home/user/skeleton/trunk/db
Adding /home/user/skeleton/trunk/doc
Adding /home/user/skeleton/trunk/doc/ABOUT
Adding /home/user/skeleton/trunk/RELEASE-NOTES
Adding /home/user/skeleton/trunk/UPGRADE
Adding /home/user/skeleton/trunk/FAQ
Adding /home/user/skeleton/trunk/data
Adding /home/user/skeleton/trunk/README
Adding /home/user/skeleton/trunk/util
Adding /home/user/skeleton/branches
Adding /home/user/skeleton/tags

Committed revision 1.

Your project is now ready to check back out and start working on:

cd ~
svn co file:///path/to/repos/projectname/trunk work

Gives this result:

A work/HISTORY
A work/LICENSE
A work/www
A work/www/media
A work/www/media/index.html
A work/www/media/img
A work/www/media/img/index.html
A work/www/include
A work/www/include/css
A work/www/include/css/index.html
A work/www/include/css/style.css
A work/www/include/index.html
A work/www/include/js
A work/www/include/js/index.html
A work/www/index.html
A work/db
A work/doc
A work/doc/ABOUT
A work/RELEASE-NOTES
A work/FAQ
A work/UPGRADE
A work/data
A work/README
A work/util
Checked out revision 1.

A final note — if you are using Subversion, DO NOT mess with the .svn directories anyplace within your project! When you are deploying the project to a web server (testing, production, etc.), you can just exclude them (use the -C switch for rsync, for example).

Keywords for the search engines: subversion repository directory structure template layout example sample recommended web app webapp application