Organizing projects in SVN

Question

I'm fairly new to SVN and I would be interested in hearing about how other people would organize projects in SVN.

We have projects that have different types of source files: C#, SQL, and Matlab. In addition to these types of files, we have Excel and Word file reports that we do not intend to put into SVN.

So let's say we have a projects directory:

Projects\
Projects\Project1
Projects\Project2
...

Now for the SVN repository, would it make sense to categorize things by source file type (C#, SQL, Matlab) then project:

SVN\C#\Project1
SVN\C#\Project2
SVN\SQL\Project1
SVN\SQL\Project2
SVN\Matlab\Project1
SVN\Matlab\Project2

Or would it make more sense to categorize things by project first then source file type:

SVN\Project1\C#
SVN\Project1\SQL
SVN\Project1\Matlab
SVN\Project2\C#
SVN\Project2\SQL
SVN\Project2\Matlab

Or maybe there's a better way to do this?

Also, what is the best way to indicate in the Projects folders (not SVN) that a project contains files saved in SVN? Like, if I went into a the project folder for Project1 (Projects\Project1) and only saw Excel and Word reports, what would be the best way to indicate that there are other files checked into an SVN repository?

Also, how does everyone feel about putting checked out SVN files on shared drives? So for instance, let's say Projects\Project1 contains the following files:

Report1.doc
Script.sql (This is a checked out SVN files in the Projects folder, which is a shared network drive)

In this situation, it would be very easy to see when there are SVN files used with a project, BUT having the checked out SVN file on a shared drive would make collaboration much more difficult. Is this others do to?

I don't understand your last question about "checked out" files on a shared drive. Why would you do that? Are you sure you understand the purpose of SVN? :) — Andres F., Feb 03 '12 at 15:14
@AndresF., I completely agree with you, this is an idea my coworker is suggesting. His reasoning is that with checked out SVN files on the shared drive, there's not another location for people to find files associated to a project. That's just another level of complexity that will make life a lot more difficult for the non-technical people on our team. It does certainly defeat the purpose of SVN in my ways, but it makes things a little easier. I came here to see if anyone else agreed with his idea or if there is a better alternative. — sooprise, Feb 03 '12 at 15:35
An SVN repo can be configured to be browsed using Internet Explorer, so non-technical people can still see your reports (they can even bookmark the URLs!). If you want them to be able to edit the reports, you will have to train them to use something like TortoiseSVN, which is not too hard: it integrates directly with Windows Explorer. — Andres F., Feb 03 '12 at 15:41
I just tried making modifications to a .xlsx file and checking it in and making modifications of the same file in a different checkout. The conflicts were really impossible to read, it seems best too keep these out of SVN since because conflicts are so poorly handled, collaboration isn't as easy. — sooprise, Feb 03 '12 at 17:44
SVN can't solve conflicts in binary files; its merging capabilities are meant for text-based files such as source code! This doesn't mean you cannot check-in binaries such as Word documents or JPEGs -- in fact this is extremely common. It just means you cannot merge binaries. One way to make sure you don't get conflicts is locking your binary files (your reports) by using the svn lock command. Don't give up on SVN yet, the use case you're describing is not at all uncommon. — Andres F., Feb 03 '12 at 18:00
Let me know what you think of this. Even with locks, I'm still a little resistant to use them and incorporate all of our project files into an SVN trunk. The reason for this is if I want to make a modification to an Excel report, I have to update to the most recent version, make my changes, save them, and then check them in. For more technical source code files, I think this procedure is ok, but for excel files that have to be used by a lot of people, I think there would be a lot of pushback if everyone had to have SVN just to view them. — sooprise, Feb 03 '12 at 18:23
@sooprise: You are going to have to deal with merge conflicts when many people are editing a single file, no matter what format it is. In your shared directory example: I open the file, then you open the file and save a change, then I save a change. Your edits are lost. The advantage of version control is that even if I commit my changes without incorporating any of your's, you can always step back to the previous revision and correctly merge the data. As for push-back, some times you have to tell people this is the way it is going to be and explain why this is better. — unholysampler, Feb 03 '12 at 18:44
@sooprise Basically what unholysampler said. You will have to implement some way of handling conflicts anyway, regardless of whether you use SVN or a shared drive. With SVN, at least you have a history of changes! — Andres F., Feb 03 '12 at 19:02

Andres F. · Answer 1 · 2012-02-03T18:14:31.077

9

You have three questions there:

It makes more sense to group by project, i.e. svn\project1\whatever, since "project" is the most meaningful category. Why would you group completely unrelated projects just because they are implemented in C#?
Not sure I understand your second question. With SVN, files in your working copy may have several possible statuses: checked in, dirty (i.e. you have uncommitted local changes), ignored (i.e. local files not managed by the repository), etc. Use an UI such as TortoiseSVN (if you are using Windows) and it will nicely show you the "status" of each file. Or you could use the command line as well, but that's less user friendly.
"Also, how does everyone feel about putting checked out SVN files on shared drives?" This question makes me think you don't entirely understand the purpose of using a source versioning tool such as SVN. The purpose of checking out files is for you to have a local copy to work with. If you share this copy, especially if you provide write access to it, you are defeating part of the purpose of using SVN to begin with!

Note that SVN cannot gracefully handle conflicts in XLS and DOC reports, because they are binary files (you'll get a conflict if two people try to modify and commit the same file). Merge/diff in SVN is meant for text-based files, such as source code, not for binaries. One way to solve this problem is to lock your binaries for editing. This can be done using the svn lock command (or the corresponding option from an UI such as TortoiseSVN).

You may want to read an explanation of when locking is necessary. It's relatively easy to understand.

edited Feb 03 '12 at 18:14

answered Feb 03 '12 at 15:09

Andres F.

5,139
2
30
41

User friendly depends on a number of things. If you are not on Windows, the command line is a better friend. – unholysampler Feb 03 '12 at 15:13
Maybe so, but let me guess that the OP is using Windows ;) – Andres F. Feb 03 '12 at 15:16
Let me clarify my other question. Let's say we have a shared drive called the S drive which contains project folder called S:\Projects\Project1, which contains Report.doc, and Script.sql. Script.sql is actually a file that is checked out from the SVN repository that just lives on the S drive so that people know there is a file associated to this project in SVN. Because this checked out file is on a shared drive, if two people try working on it, they would have to create their own local copies, which almost defeats the point of having it on the shared drive at all. Does this make sense? – sooprise Feb 03 '12 at 15:18
@sooprise I think I understand you. It's a bad idea for people to edit your file Script.sql on the shared drive. People can figure out what files are there by browsing the SVN repo directly! No need for a shared drive at all. – Andres F. Feb 03 '12 at 15:22
@AndresF., the shared drive is still necessary to hold Excel and Word reports which will not be checked into SVN, or am I making a blunder to assume only code files should be put into the repository? Is it common to include all sorts of files in SVN even if they are not code files? – sooprise Feb 03 '12 at 15:28
1

@sooprise: Any content that is important to the project and evolves with time can be put in version control. Content that isn't source code should should be in a different folder under the main project directory in order to keep things from being jumbled together. – unholysampler Feb 03 '12 at 15:35
@sooprise It depends on what those files mean to your team. SVN is especially good at handling plain text files, but can also handle binaries such as images, XLS or Word files (it's just less efficient at handling them). It's not unusual to check in documentation files for your project, for example. Do your reports need to be seen and changed by the whole team? Are they autogenerated by some tool (if so, they are good candidates to exclude from the repo). – Andres F. Feb 03 '12 at 15:36

Caleb · Answer 2 · 2012-02-03T15:55:49.210

1

What's the benefit of segregating source files based on language? Why put all the resources (code, images, configuration files, etc.) in the same project directory? I'd stick with the conventional SVN layout and have subdirectories for trunk, branches, and tags:

Projects\
    Project1\
        trunk\
        branches\
        tags\
    Project2\
        trunk\
        branches\
        tags\
    ...

Within a project directory such as trunk, you'd have all the files that you need to build the project. If it makes sense to divide them into subdirectories, do it, but make sure that there's some benefit to the organization. For example, you might have a directory for artwork so that you can let your graphics team access those files but not the source code, and your programmers can access the source code but can't change the art. Or, it might just make it easier to copy all the image files to the right spot in the product during the build process. If it makes sense to segregate files by language, there's nothing wrong with doing that too. Just know why you're doing it.

Take a look at Version Control with Subversion for a great deal of helpful information. For example, there's a chapter on administering a repository that starts off by considering repository organization.

edited Feb 03 '12 at 15:55

answered Feb 03 '12 at 15:28

Caleb

39,147
8
95
152

@unholysampler, is it standard to have trunk, branches, and tags directories per project? That's something else I was wondering about. Currently in SVN we have things split up by language, and each language folder has the trunk, branches, and tags folders inside. It sounds like from the comments here that we'll split things up by project, but I'm still unclear if there should be these trunk, branches, and tags folders for the entire projects folder, or per project folder. Thanks :) – sooprise Feb 03 '12 at 15:40
The trunk, branches, and tags directories are the usual convention. There's nothing in Subversion that enforces that -- you can organize your stuff any way you like, but if you stick to the convention other people will have an easier time relating to your repository. – Caleb Feb 03 '12 at 15:51
I'm wondering if you should put trunk, branches, and tags in SVN\Projects or in SVN\Projects\Project1, SVN\Projects\Project2 etc – sooprise Feb 03 '12 at 17:46
Put them in the individual project directories: Projects/Project1/trunk, Projects/Project1/branches, etc. The trunk directory will, depending on how you use it, contain the main line of stable development code, or perhaps the current distribution code. Branches are typically used for new development until that new code is ready to be merged into trunk. Read the book I linked -- it's free, and there's a lot of good info in there. – Caleb Feb 03 '12 at 17:54

score -1 · Answer 3 · edited May 23 '17 at 12:40

You know, in SVN most popular folders sheme for "things" is trunk, branches, tags.

Now, how to choose what kind of "things" to use for above scheme?

My preferred way to arrange SVN structure can be called "versioning-driven". Not that it's particularly "my" way, just one suggested by more experienced colleagues. Anyway it's one that has been proven to work best for me.

Versioning-driven means things are defined by whether you find it convenient to have dediccated versions sequence for this kind things, like version 1.0, 2.0, 3.1 etc. anything you want to be "within" that version sequence, makes single SVN "thing". Anything you would find convenient to release under different "version streams" gowes to different SVN "things".

- This product release is composed from component1 version 1.23, component2 version 4.56 and component3 version 7.98. where can I get code for component1 used in this release?
- Code for component1 v1.23 is in SVN folder component1/tags/1.23

- There was patch 666 we did for component2 version 4.3.1 two years ago. Where I can get its code? I am particularly interested in releases 1.0 and 2.0
- That's easy. You can find patch code in SVN folder component2/branches/4.3.1.666 and releases in component2/tags/4.3.1.666.1.0, component2/tags/4.3.1.666.2.0

You see, above has basically nothing to do neither with project nor with source file type.

If I need say particular "mix" C#, SQL, Matlab to be released/versioned as a whole (component1 ver 1.0, 2.0, ...), these would go inside one "thing" - having same trunk, tags, branches.
If I need some bunch of C# files to be released/versioned separately of another bunch of C# files (component2 version 4.56 and component3 version 7.98), these would go to separate "things", each having dedicated sub-folders trunk, tags, branches.

As for the projects, SVN folders for these are, again, versioning-driven. If I can think of versions 1.0, 2.0, etc of the project, to me it means the need for own SVN "thing" - own folder "project-name" with trunk, tags, branches sub-folders inside.

Organizing projects in SVN

3 Answers3

Linked