My employer uses TFS VCS as more of a shared storage location for source code rather than source control with clear policies and branch owners to help organize things. I've been given a mandate to clean things up, so I am looking for strategies on how to reorganize an existing repository without losing history, creating unnecessary churn, and insulting my co-workers.

Would it be better to move existing code to a single root folder and start new MAIN and DEV folders at the top level? Or would it be better to create a completely new TFS project?

When I Google reorganize source control repository, I get results on how to organize from the get go. Can anyone point to sources on reorganizing? Would be cool to find a collection of source control refactorings.

1 Answer 1


How to reorganize

If you do the reorganization wrong, you'll eventually have to deal with the angry team. In the best case, they will just revert your changes; in the worst case, they will have to deal with the new organization, even if they find it highly irrational. You can easily avoid this.

creating unnecessary churn, and insulting my co-workers

Don't do it alone. Talk with your coworkers. Prepare a reorganization plan together.

Discuss the branching strategy with your coworkers as well. You're probably not in a position to decide which one would be better for everyone, so you have to consider what your colleagues are thinking of different strategies (and their opinion is way more important than an opinion of some guy from SoftwareEngineering.SE, especially since we don't know anything about the project topology and organization, the team and their past experience and habits).

Note that your team may also decide that there is no need for reorganization, for three possible reasons:

  • The codebase is good enough. Yes, it may not be the best codebase out there, but if the team knows it well, it may be perfectly OK for now.

  • This is not a good moment for it. If you worked on a non-Agile project for the last eight months and you are about to ship the first release in two weeks, you may postpone touching to the repository for now.

  • The reorganization can be made through small changes over time. In other words, there is no need for one big reorganization. Just like in a codebase, you may have major changes which would affect hundreds of classes, but you'd better make small, localized refactorings, each one moving you towards the target while ensuring everything works well. Reorganization of the repository is very similar: what if you spend four hours reorganizing all the stuff around, and when you finish, you find that the build is broken, and that while you can build the project on your machine, 80% of tests now fail?

When to reorganize

Once your decided that the repository needs a big reorganization which can't be done through many small steps, the next question to answer is when to do it.

  • Agree on a date when the repository will be reorganized, so that your colleagues would get ready for it by committing all the pending changes before leaving in the evening. The day of the migration, make sure to remind your coworkers to commit their changes at lest twice (for instance during morning's standup, and personally to every member of the team when you see that the person is about to leave in the evening).

  • Do the backups.

  • Do the damn backups. Seriously. Things happen, and you don't want to explain to your coworkers that all the work they did for the last week was lost, because automated backups were configured to run once per week.

  • If possible, do the reorganization at night, when nobody is working on the source code. Make sure you have enough time and resources for a case when something goes wrong. What if the build starts to fail once you reorganize the repository? What if some tests start to fail? What if there are warnings reported by the Continuous Delivery?

  • Once the operation is finished, send an e-mail to your team, explaining the changes which were made, the new organization, and the decisions you took during the reorganization.

  • Be with your team the next morning, to assist them if something goes wrong when they update their local source or if they don't understand the new organization.

What to reorganize

As I already explained, it's up to your team to decide exactly what should be the new organization.

Different developers won't even agree on branching strategy: One developer may prefer one branch per feature; another one would suggest a branch per developer. I usually suggest to commit directly to trunk, which works for me and for several of my colleagues, but would fail completely for other teams.

Similarly, it's even more difficult to give a magical solution to how files should be organized, without even knowing the current topology of your repository.

However, I can suggest a few things which may apply to most projects and which had positive results in my case in the past. Remember, if your team suggests the opposite, you should absolutely take their opinion over mine:

  • Don't create a new TFS project. I'm not sure if history can be preserved across TFS projects (and whether it's easy to do), but even if it is, I don't see the point: the only case where you would do it is if a separate team/company will continue working on the old project, which is not your case.

  • Don't do old area/new area. You are reorganizing for a good reason: because your team decided that the old organization sucks. There is no need to keep it in any form. Forget about it. Move, don't copy.

  • Remove stuff aggressively. There is a prototype your team wrote a year ago, and the concepts shown by this prototype were implemented in the project? Get rid of the prototype. There is a project you started but abandoned six months ago? Remove it. The benefit of version control is that it keeps everything, forever, so you know that if you need something which was removed, you can still find it. This is exactly the same as cleaning your project by removing code which is not used any longer.

  • Deduplicate. Obviously, if you have duplicate stuff, get rid of the duplication. This also often leads to the following point:

  • Rely on proper dependency management. Since you're talking about TFS, I would suppose that you deal with .NET projects. If you find DLLs stored within the repository, this is a very bad sign: you shouldn't be doing it, but instead, using NuGet to handle dependencies for you. For dependencies between the components written inside your company, there is such a thing as private NuGet servers.

  • Clean up the mess. While Visual Studio does a decent job of automatically ignoring the files which should be ignored at version control level, it happens that some files such as user settings or binaries still get in. They have no place in a version control, so get rid of them.

  • Put non-development stuff outside version control. If you work with graphical designers, you may end up with Photoshop documents checked in the version control. This is not a good idea, because too many binary documents changed too often could bring your version control to knees. Non-developers successfully use different revision management strategies than developers, thus, there is no place for them in TFS.

    Note that if you actually have non-development stuff in the repository, then your reorganization meetings should also include people who work with this stuff. If they actually do benefit from version control, setting a dedicated repository (and probably even a dedicated server) for them would be a good idea in order to keep yours clean from binary content.

  • KISS. I've seen technical leads drawing magnificent diagrams of branches and merges in all directions. Maybe those guys are very smart, but it often appears that they are the only one who actually understand all this mess, and often even they don't bother using it later. Both project structure and branching should be as simple as possible. For project structure, prefer flat one over an hierarchy. It's OK if you end up with a list of five hundred directories because you have five hundred projects; much more problematic would be to ask yourself six months later if the project which helps accountants to generate PDF invoices from CRM should go to “Customer relations”, “Accounting”, “Tools” or “Misc”. More about trees on UX.SE.

Note: working in the past as technical lead, I had a few situations where I had to reorganize the source repository or move the source from one system to another (such as SVN to TFS). Every time, the operation went well. Not because I'm good at it, but because we worked as a team deciding together what to do, when, and why. Once everyone was happy with the decisions we took, I just had to stay late in the evening and simply perform the operations by following our plan.

  • Your process oriented advice is well taken as is your advice against starting a new project, but do you not have any advice for bringing order to an unorganized repository? Do I tuck all the existing stuff into an "old" area or do I start "new" area? Surely it is the policies around what goes where that will help the most, but someone needs to simplify this thing, as giving advice on where to commit code has become difficult.
    – flipdoubt
    Nov 15, 2016 at 21:53
  • @flipdoubt: I edited my answer to address your concerns. Nov 16, 2016 at 1:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.