Skip to main content

Trunk-based development workflow

What is a trunk-based development workflow?​

In the trunk-based development workflow, users always commit changes directly to the repository’s trunk directory (the repository’s main branch), without creating any other branches.

This simplest workflow can be sufficient for small and medium-size teams. It lets multiple users collaborate on the same project and lets them conveniently receive changes made by their teammates.

Sometimes, the term trunk-based development is understood more loosely. Some people use the term trunk-based development to mean a strategy similar to the feature branch workflow, but with very short-lived branches that are frequently merged back into the trunk. This page assumes the stricter definition of the trunk-based development workflow where branching isn’t used at all.

Example scenario​

To illustrate this workflow with a concrete example, let us assume that your repository is named MyRepo and is reachable via a Subversion client at the following URL: https://svn.example.com/MyRepo/

Let us also assume that the repository has the conventional single-project repository layout: i.e. has directories named trunk, branches, tags in the repository’s root directory. And suppose that the trunk directory already contains one file called README.txt.

MyRepo
  ├── trunk
  │   └── README.txt
  ├── branches
  └── tags

The steps below assume that you have already checked out a working copy from the repository to your computer. Based on the example of the repository described above, you can check out the trunk directory from that repository to a local working copy as follows:

C:\Users\Alex> svn checkout https://svn.example.com/MyRepo/trunk my_work_dir

This command will check out (download) the contents of the repository’s trunk directory to a new directory called my_work_dir on your computer. In our example scenario, my_work_dir will now contain a file README.txt.

Step 1: Update the working copy​

Before you make edits in the working copy, your working copy should contain the latest versions of all your project’s files and directories from the trunk.

If your working copy was not checked out or last updated just moments ago, update the working copy as the first thing you do, before you make any changes in the working copy.

Navigate into the root directory of your working copy. To update the whole working copy, run the svn update command in the root directory of your working copy:

C:\Users\Alex> cd my_work_dir
C:\Users\Alex\my_work_dir> svn update

This update ensures that any changes you make in the working copy on Step 2 will be made on top of (relative to) the most recent state of the trunk. This is important, because Subversion won’t allow you to commit new changes that are made to out-of-date files and directories. Making local changes to up-to-date files and directories also minimizes the likelihood of potential conflicts on Step 3 when you are ready to commit your local changes.

Step 2: Make changes in the working copy​

You can now make any desired changes in this working copy. For example, you can edit the README.txt file. Since README.txt was received from the repository, it is already versioned (under version control). So your Subversion client is automatically tracking any edits that you make in README.txt in the working copy.

Then you can run the svn status command at the root of your working copy to check the status of all files in your working copy:

C:\Users\Alex\my_work_dir> svn status

The svn status command will show you your local uncommitted changes. That is, it shows files/directories in which you made changes in the working copy, but have not committed the changes to the repository yet.

For plain text files, such as README.txt, you can also see which particular lines you have edited in the file by using the svn diff command:

C:\Users\Alex\my_work_dir> svn diff README.txt

See the Make Your Changes, Review Your Changes and Fix Your Mistakes sections in the book Version Control with Subversion for more details about this step.

Relevant best practices​

The following best practice is relevant on this step:

  • Always tell Subversion when you rename or move an item in the working copy. If you want to rename or move a file or directory within the working copy, rename and move it explicitly with svn move. That is, you should use svn move or its equivalent in the Subversion GUI, to tell Subversion about this renaming or relocation. For example:

    C:\Users\Alex\my_work_dir> svn move README.txt RENAMED_README.txt

    If you rename or move an item to a new location without this, to Subversion it will look as if that previously existing file had gone missing from the working copy, and a new unrelated unversioned file was created in the working copy.

Step 3: Commit your changes​

Commit your changes to the repository:

C:\Users\Alex\my_work_dir> svn commit -m "My descriptive log message."

Running this command from the root of the working copy commits all the changes that you made in this working copy. Make sure to add the -m option followed by a commit message (in double quotes) describing your changes.

After committing your changes, you can return back to Step 1 and continue your work in this working copy.

What if the file being committed is out of date?​

The commit might fail if you attempt to commit changes to items that are already out of date in your working copy. Subversion will only allow you to commit changes that are relative to the latest state of the affected file in the repository.

If the commit fails stating that any of the committed files are out of date, you now should update your whole working copy first, just like you did on Step 1, so that your local changes will be relative to the most recent state of the affected file in the repository:

C:\Users\Alex\my_work_dir> svn update

When updating your working copy to get the latest changes from the repository, you may occasionally run into a conflict. Typically, this occurs if in the repository your teammates edited the same lines in the same file as you did locally in the working copy, and your local changes contradict theirs. Just like in any version control system, Subversion needs your input to decide whose edits are preferable in this case. For more details on conflicts, see the Conflicts page. For information on how to resolve them, see the Handling conflicts chapter.

Once the working copy is up to date and does not contain any unresolved conflicts, Subversion will allow you to commit your changes.

Conclusion​

The trunk-based development workflow described above is Subversion’s simplest workflow, which does not involve branching. It is quite suitable for small and medium-sized teams, but has the following limitations:

  • It does not provide a way to ensure that the trunk always contains finished and approved work, because there is no opportunity for other teammates to review changes before they get committed to the trunk.
  • It is not well suited for committing substantial experimental changes, since commits would affect everyone by affecting the main line of the project’s history.
  • Additional care is required to keep the trunk in a working state, users should not commit unfinished work that breaks the project.
  • It does not scale well to large teams.

These limitations can be overcome through the use of the feature branch workflow described further. Both the feature branch workflow and the trunk-based workflow can be used alongside each other on the same project.