Version Control Using Subversion

What Is Version Control?

A version control system (VCS) archives past versions of the files under control. It also provides for easy comparison, merging, and reversion. These activites are known as version control or revision control. A VCS allows you to easily:

• track how your files change over time

• back up every version of a file

• experiment with related versions (by branching)

• merge successful experiments into your document

• revert to an earlier version of a file

• work with other people on the same repository of files

• see which collaborater made which changes

Text Files vs Binary Files

The most popular version control software works best with plain text files. Usually you will not put binary files under version control.

Examples of plain text files:

Source code, LaTeX, reStructuredText, comma-separated values, etc.

Examples of binary files:

Image files, word-processing files, spreadsheet files (except CSV and TSV), etc.

Why Subversion?

There are many different VCSs, with varying advantages and drawbacks. Subversion is particularly simple and powerful. Among the alternatives to Subversion, git is very popular. However, as a distributed VCS, it is inherently more complex. Subversion offers fewer opportunities to shoot yourself in the foot. It includes the following features.

• full project history

• central repository

• parallel editing

Full Project History

All committed versions of a document are maintained forever (unless the entire repository is deleted from the server).

• SVN tracks the entire evolution of a document.

• additions, deletions, and changes to a document are tracked on a line-by-line basis

• incremental changes to a document are committed under a new revision number each time

• the date and time of a new revision is maintained along with the user who committed it

Central Repository

Subversion documents are securely accessible in a single place: the repository. This is the official master copy. To use Subversion correctly, you must keep your working copy (on your computer) synchronized with the repsoitory copy.

Subversion uses a central repository. The repository for our project is on campus.

• Versions of a document are tracked in a single place, the repository

• Documents are accessible over the internet (via SSH tunnel)

Parallel Editing

Subversion tries to simplify collaboration. It does not use a “check-out/check-in” model with locked documents. Several people can simultaneously contribute to a single document, and long as the do not try to work on the same section of the document.

• Changes made to the same document by different users are usually merged automatically (although occasionally this must be done manually).

• Hint: use frequent updates and the UMUTC protocol to minimize manual merging. (Update, Modify, Update, Test, Commit)

Respository vs Working Copy

We will not be concerned with the server side, other than to note that our repository is a folder on the Subversion server. That server is a computer on campus. Each student will check out a working copy of the repository to their own computer.

repository:

the reference copy for everyone; a folder of files (and folders) on a server

working copy:

your personal copy of the repository, along with any changes your have made, stored on your personal computer

Your working copy is created when you “check out” a copy of the repository. A check out copies the contents of the repository (on the server) to your personal computer.

When you change the working copy on your personal computer, then your working copy no longer matches the repository. You need to commit those changes to the repository, so that everyone has access to your changes.

Useful documentation:

http://svnbook.red-bean.com/nightly/en/svn.basic.version-control-basics.html#svn.basic.repository

Know Your Command Shell

Before installing Subversion, you need to know a bit about using your command shell to move around and create folders.

• Windows: https://www.youtube.com/watch?v=FpRGRLI8Fy8 (first 10 minutes)

• Mac: https://www.youtube.com/watch?v=ogWoUU2DXBU and https://macosx-faq.com/open-terminal-current-folder/

Installing Subversion

Windows:

Most students should download the latest Subversion (Windows 64-bit) from Collabnet. http://www.collab.net/downloads/subversion (Just Subversion, not Subversion Edge.) Get the 64 bit version.

OS X:

Student who can should simply download the latest Subversion (Windows 64-bit) from WANdisco. https://www.wandisco.com/source-code-management/subversion#osx Install the file and follow the prompts. Once installed, open Terminal and run the command export PATH=/opt/subversion/bin:$PATH to set update your search path.

You may find that your Mac will not open this without a security override. If you are comfortable doing so, you can provide this override. Otherwise, you must use the alternative methods below. (Or, at your own risk, go to System Preferences » Security & Privacy and click “Open Anyway”.)

Alternative: use a package manage to install on OS X:

Installation with a package manager on a Mac is a bit more involved, unless you have already installed the package manager.

1. Install XCode from the Mac AppStore. Note that XCode is a huge download. Use a wired connection if possible. A wireless download may take hours.

2. Install XCode’s command line tools via the menu: Xcode » Preferences » Downloads » Command Line Tools » Install.

   Alternatively, open Terminal and enter the following:

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -license accept
   xcode-select --install

   If the last step produces a message that the software cannot be installed because it is not currently available from the Software Update Server; do not worry. This should mean that you already installed the latest version.

3. Install Subversion via MacPorts (recommended) or Homebrew (not both)

   MacPorts:

   1. If the Macports package manager is not on your computer, download the Macports installer from https://www.macports.org/install.php and then double click to install it.

   2. Open Terminal and enter:

      sudo port install subversion

   Homebrew:

   1. If the Homebrew package manager is not on your computer, use Terminal to install Homebrew with these two steps.

      /bin/zsh -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
      brew doctor

   2. Open Terminal and use Homebrew to install Subversion by entering:

      brew install svn

      Here is an online discussion:

      https://www.howtogeek.com/211541/homebrew-for-os-x-easily-installs-desktop-apps-and-terminal-utilities/

Other:

Apache lists other ways to get Subversion for various operating systems: https://subversion.apache.org/packages.html

Command Shell

To enter Subversion commands, you will need to become familiar with a command shell. Windows users should use the PowerShell shell, which ships with Windows. Mac and Linux users may consider installing PowerShell. Mac users usually use their Terminal shell instead. Linux users usually use their bash shell instead.

Windows

On Windows, find PowerShell under Start > All Programs > Windows PowerShell.

Mac

OSX provides Terminal (which provides a zsh shell by default).

Linux

Use bash.

Example: Test Your Installation

Launch your command shell. In your command shell, enter the following Subversion command.

svn --version --quiet

If you correctly installed the software, your shell should print the Subversion version number. For more information about your working copy, including the revision number of your checkout, enter the following subversion command.

svn info

Change Directory (i.e., Change Folder)

When you launch your command shell, the default working directory is not usually where you want to be. (The terms ‘directory’ and ‘folder’ are synonyms.) You will need to change your working directory. We use the cd command to "change directory".

Change directory to where you want to place your new folder. For example, this may be a folder holding all your files and folders for this course.

Use Command Shell to Make a New Directory

Instead of using the file explorer GUI application, use a command shell to to create a new directory. After using cd to change to the the existing directory that will hold the new directory, use the mkdir command to make a new directory. For example, let us make a directory for Economics 450 coursework.

mkdir econ450

Once you have created a new directory, you can change into it using the cd command. This stands for “change directory”. E.g.,

cd econ450

I will assume that you have take both steps. Then you are ready to check out a working copy from the Subversion repository into your new econ450 folder. This econ450 directory will hold all of your course work. It will also hold a special folder, which we will soon create. Note that econ450 is just a regular folder, which not under version control.

Use Useful Names for Your Files and Folder

Decide on a name that you will give your new directory, which will hold your working copy.

Your next task is to copy the repository folder (which is on the server on campus) to a new working-copy folder (on your personal computer). This is called a checkout of the repository, and you only do it once. The copy of the repository is your working copy. Using Subversion, you will be able to modify the working copy by adding files, deleting files, and making changes to existing files.

Partial Summary of Steps So Far

Here is an example. Suppose you want to store all your coursework for Econ 450 in an econ450 folder. Insider this folder will be another folder, say svn450.

1. Launch your command shell.

2. Use cd to change to the folder where you want to create the econ450 folder.

3. Create the econ450 folder like this:

   mkdir econ450

4. Use cd to change into your econ450 folder:

   cd econ450

5. Create your working copy with the svn checkout command:

   svn checkout <etc>

Working Copy

working copy

In most regards, this is an ordinary directory on your computer. Howevever, it is treated specially by Subversion: this folder is under version control. You create this folder by doing a checkout.

(Advanced: Subversion adds special hidden subdirectories named .svn to implement this version control.)

checkout

• pick a name for your working directory.

• svn checkout <repositoryURL> <workingDirectoryName>

This command gets the latest versions files contained in the repository associated with repositoryURL (as described in the previous slide).

You will usually find it best to avoid using spaces in the name of the folder for your working copy.

Example: Checking Out a Working Copy

1. Use the cd command to change to the folder in which you want to create a folder to hold your working copy

2. A class depository has already been created for you. Check out this repository as follows by entering the following on a single line in a command shell:

   svn checkout
     <repositoryLocation>
     <localFolderName>
     --username <userid>
     --password <pw>

<repositoryLocation>

the location of the repostory; e.g., a URL

<localFolderName>

the name of the folder you want Subversion to create to hold this checkout (without the brackets)

<userid>

your username

<pw>

your password

In each case, make an appropriate substitution (without the angle brackets).

For example, assume you plan to name the folder holding your working copy svn450, and you will put this new folder in your econ450 folder. The following discussion pretends your username is jdoe2023 so that your password is jdoe2023@american.edu. After making sure that you are in your econ450 folder, enter the following in your command shell (on a single line):

svn checkout
  https://subversion.american.edu/svn/econ450x2023
  svn450
  --username jdoe2023
  --password jdoe2023@american.edu

Note that there are no angle brackets here. Of course you need to substitute your specific information, making use of your AU username.

If yout did this correctly, then you should have a folder structure that includes the following. Remember, econ450 is just an ordinary course folder; inside it is the special svn450 folder, which contains your checkout of the repository.

econ450
└── svn450
    └─  prof

Adding and Removing Files

Add version control to a file or folder like this:

svn add <file_or_folder>

where you substitute the filename (without the brackets) for <file>. (Use the --depth=empty option to add a folder without its files.) To keep things simple, I recommend that you do not use spaces in filenames. (However, you can surround a filename with quotes if it contains spaces".)

Once you svn add a folder or file, it is under version control forever. Do not use other software to move it or remove it! You must use the Subversion commands, or you will create problems.

svn delete <file>

If you are removing a file from the repository but wish to keep the local copy, use the --keep-local option.

svn delete --keep-local <file>

Keep Your Code Current

1. Communicate: only one person should be changing any one procedure at any one time. (However, two people can simulatneously work on two different procedures.)

2. Completely close your code editor while interacting with the repository.

3. Use the following UMUTC protocol when you start working on your code.

• update your working copy

• make changes and test them

• update your working copy

• test that your working copy still functions

• commit your changes

UMUTC Protocol

Make sure you follow the UMUTC protocol with communication.

Communication:

Let your group know what code you will be modifying. Make sure two people and not simultaneously working on the same subroutine.

UMUTC protocol:

• update from the repository (use svn update)

• modify and save your working copy (e.g., a NetLogo file)

• update (use svn update)

• test (e.g., run Check in your NetLogo Code tab)

• commit (use svn commit)

Communication vs Conflicts

Even when following the UMUTC protocol, communication is crucial. Make sure two people are not simultaneously changing on the same part of the code in any way, including adding comments or notes. If you violate this, you will create a conflict that Subversion cannot fix for you. You are at risk of a conflict until you successfully commit your changes, so update and commit every day.

Checking on the Adequacy of Communication

Updating a file merges the repository version with the working copy. If another user previously committed a conflicting change, the update will put the file into a conflicted state. Resolving conflicts is a pain worth avoiding when possible, which is why adequate communication (and frequent updating) is so important. Prior to an update, one may check for what is new in the repository version of the file fname.txt with the diff command.

svn diff -r BASE:HEAD fname.txt

Note that HEAD is a special name that refers to the version in the repository, while BASE is the the last repository version you updated your working copy to, as it was archived in the repository. Keep in mind that BASE therefore does not include changes to the working copy that were subsequent to the last update. Similarly, when you svn update a file or folder to HEAD, then BASE and HEAD become equal.

Finally, we often want to see how our working copy differs from the repository. For this use:

svn diff -r HEAD fname.txt

A Special Consideration for NetLogo Users

NetLogo users need to carefuly communicate when adding experiments. If two experiments are added at the same time by two different users, the one who commits second may see a conflict. So make sure to alert each other so that the experiments are added sequentially: one person adds and commits an experiment, everyone updates their working copies, and after that the next person adds and commits an experiment.

Another Special Consideration for NetLogo Users

If you change your NetLogo Interface in any way, these changes will be saved when you save your model. So communication includes discussion of such changes.

This includes resetting any sliders or choosers. This too can be a source of conflict, if two group member both move sliders around. So be sure to run your startup procedure (which should set all sliders and choosers) before saving and closing your NetLogo model.

Update

You can update all files in your working directory to the latest revision in the repository, or just a single file. The update command can also fetch a revision different than the latest revision with the -r flag.

• svn update

• svn update [filename]

• svn update -r n [filename]

Here n is the desired revision number.

Modify and Test

• Edit your working copy (and save your changes to the file).

• Add or delete files.

After saving your changes, always test that your changes leave the code in runnable condition.

Update

After editing files, saving your changes, and testing them but before committing them, do another update (following the steps above).

• Close the application you are using to edit the file. (This is advisory: it ensures your application does not lock the file, and it ensure that you end up working on the changed version.)

• Again run svn update to ensure your changes are compatible with any commits others might have made while you were working. (See the section on Merging_.)

Test before Committing

Final tests ensure that your changes are compatible with any commits that took place while you were working. Before committing, always test that the code is in runnable condition. Ensure that you do not commit broken code.

Committing Changes to Existing Files

Use Subversions commit command to commit your changes to the project repository. Each commit must be accompanied by a message, which explains the purpose of the commit.

svn commit --message="a commit message"

The actual message must be surrounded by quotation marks. If you omit the --message option, then Subversion will try to start an editor to ask for a commit message. If you also have not set an editor, Subversion simply refuses to commit and will give you an error message.

After committing your changes, you can restart your work. Re-open the file in the application you use to edit this file, and continue to follow the UMUTC protocol. Remember to save your work before you update or commit.

General Precaution

As a precaution, close your editor or other coding application before you update or commit.

NetLogo Precaution

If you are using NetLogo or another ABM toolkit, you should take an additional precaution. Make sure you fully determine the default values of all interface globals in a startup procedure. Immediately before you save and exit, run startup.

The reason this is needed is a bit subtle: as late as version 6, NetLogo stores widget state when a model is saved. Suppose you and a groupmate both move the same slider but differently. When saved, the slider state is saved. This produced conflicting changes in the file: you have both changed the same line, but in different ways. Whoever commits first will not see any problem, but the second person to commit will be informed of the conflict and prompted to make a decision.

If this happens, you can respond to the prompt with tc. If you have been carefully following the UMUTC protocol, this is a fine solution. However, a better solution is to avoid the conflict altogether, by taking the precaution just described.

Here is a brief recpitulation. Make sure all interface globals (sliders, choosers, switches) are set in startup. When you are ready to commit code changes, run startup, save your model, and close NetLogo. Then commit to the repository.

Example: Adding and Committing a File

Suppose you have a new file, named myfile.nlogo, that you want to place under version control. First add myfile.nlogo to your working copy:

svn add myfile.nlogo

That working copy is only on your personal computer. You still need to make it available to everyone by committing it to the repository. So do the following:

svn commit myfile.nlogo -m "commit new file to repository"

That commit command "pushed" myfile.nlogo into the repository (on campus). Now everyone in your group can check out this file, from the repository.

To edit your working copy, you just use NetLogo like always. The only difference is you want to let your group know what procedure you are working on, so that two of you do not make changes in the same procedure at the same time. Communication is important!

OK, suppose you made changes to the myfile.nlogo and save those changes, just like you always do in NetLogo. Since you have changed your working copy, it is no longer identical to the repository copy (which is on campus). You need to fix that by committing your changes. To do that, you need to change to the command line and enter:

svn update
svn commit myfile.nlogo -m "commit my changes"

That commit command pushes all your changes into the repository copy, so now the repository copy (which is on campus) matches your working copy (which is on your personal computer).

Why did we first use update? That makes sure that before you commit your changes, you update your working copy to get any changes another group member (or me) might have pushed to the repository. Always do that before you commit. In fact, always follow the UMUTC protocol discussed above. This is very important!

Backing Out of a Commit

Suppose you commit code but then realize you should not have done so: it breaks everything. SVN lets you back out of that commit as follows.

1. extract the old version

2. re-commit the old version

E.g., suppose version 314 was the last "good" version of the code. Return your working directory to that version and recommit as follows:

svn update -r314
svn commit -message "Discard a wrong-headed commit."

Seeing the Commit History

To see the entire commit history, with commit messages:

svn log

To see a limited commit history, with commit messages:

svn log --limit=5
svn log -l5

Use the --verbose option to see exactly which files were changed:

svn log --verbose --limit=5
svn log -v -l5

See the changes over a date range:

svn log -r "{2020-11-1}:{2020-11-15}"

Merging and Conflicts

Suppose you update after you have changed your copy, but the master copy has changed as well. SVN tries to merge the two sets of changes.

If you have been careful about your communications, the changes are usually to unrelated areas of the file, and this succeeds.

If the changes overlap, SVN will merge what it can, and then ask you what to do about the rest.

You may choose to

• Accept the repository's changes ('tf', or "theirs-full"). This throws away your changes, so you have to make them again.

• Override the repository's changes ('mf', "mine-full") This throws away their changes, so they have to make them again.

• Postpone the decisions ('p') and then merge by hand. Do not attempt this unless you already fully understand what is involved.

Subversion Conflicts

Avoiding conflicts depends on adequate communication among the code developers. Different developers must not change the same part of the code at the same time. If they do, Subversion will not know which change is preferred. In this case, Subversion will report a conflict, which the developers must resolve.

Suppose for example that the repository is at revision 100 and contains ‘test.txt’. Revision 100 of that file contains a single line: ‘This is test.txt’.

You and your partner both update to r100, and then you both edit test.txt. Your partner changes the line to ‘This is test.txt!’ and commits it to the repository. The commit bumps the revision number to 101.

In the meantime, you are changing your working copy (from revision 100) of the file to "This is test.txt?" When you try to commit your changes, you get an error message:

Sending    test.txt
Transmitting file data .svn: Commit failed (details follow):
svn: Out of date: '/myproject/test.txt'

This just means that you are working with revision 100 while the repository has changed to to revision 101. You need to update before you will be allowed to commit. Subversion will alert you to the conflict. if you choose to postpone, you will see:

C   test.txt
Updated to revision 101.

The C means there is an unresolved conflict in test.txt file. You will have to handle this manually.

Simplest Conflict Resolution

The simplest conflict resolution is to sacrifice all of your changes. If the conflicted file is test.txt, then do:

svn revert test.txt

Subversion responds:

Reverted 'test.txt'

Now you can update normally. (After reversion, you do not need to run svn resolved.)

svn update

New Files

If sacrificing your changes is just too radical, then you can manually fix the conflict. This requires attention to detail. First, look in the folder containing the conflicted file. Instead of just test.txt, you will now find four files related to this conflict.

test.txt

the file with conflict markers (see below)

test.txt.mine

your version (before the update)

test.txt.r100

the previous revision, with no changes

test.txt.r101

the current repository version, with your partner’s changes

Conflict Resolution: Unfriendly

It is possible to keep all of your changes while discarding all of your partner’s changes. (Your partner may find this unfriendly.) Just copy your version (test.txt.mine) over test.txt. Then tell Subversion you have resolved the conflict.

svn resolved test.txt

The ‘resolved’ command removes the special files that were generated by the postponed conflict. Now you can commit normally.

Conflict Resolution: Manual Merge

This is the most labor intensive option. Unfortunately, it is usually the right choice.

Open test.txt in a text editor. If you now take a look at test.txt, you will find markers indicating the conflict. These compare what you changed with the changes in the repository.

<<<<<<< .mine
This is test.txt?
=======
This is test.txt!
>>>>>>> .r101

Edit test.txt to remove the markers and fix up the file, keeping or discarding whatever parts you wish. (Make sure to test your changes!) Once again, before you can commit your manually merged file, you must mark it as ‘resolved’.

svn resolved test.txt

But don't forget, you should generally update and test again before committing.

Conflicts (Recap)

Postponement is the safest action, but it will mark affected files in a "conflicted" state and insert blocks that look like this:

@@ -1 +1,5 @@
  def foo():
+<<<<<<< .mine
+   bar1();
+=======
+   bar2();
+>>>>>>> .r314

Say these lines are in foo.py. They mean that your copy of foo.py changed your function foo to call a function bar1, whereas someone already changed the repository, in revision 314, in exactly the same place, with foo calling bar2. You will have to resolve this conflict before you can commit your changes.

Resolving Conflicts (Recap)

Suppose your update and encounter conflicts. You can pick your version, or the repository version, or some other resolution.

Once you produce a version free of conflicts, run svn resolved to tell SVN that you have resolved the conflicts. Update again to make sure you are up to date. Then you can commit your changes.

Helpful Information

svn status

gives information about which files are changed or new.

svn log [file]

displays commit messages for all revisions, in chronological order, along with the associated revision number.

svn annotate [file]

shows which users made which changes, line by line with the revision number and associated user name.

svn --help [command]

displays help on any command

Comparing Revisions

The diff command is extremely useful for comparing revisions. The most common need is to compare one’s working copy to the repository copy. If you have been working on say fname.txt, check how it now differs from the repository version (HEAD) like this.

svn diff -r HEAD fname.txt

Check how you have changed it since the last update (BASE) like this.

svn diff -r BASE fname.txt

Check how it differs from an old version that was not under version control.

svn diff --old <path-to-old-fname.txt> --new fname.txt

GUI Subversion Clients

There are many GUI Subversion clients. I strongly recommend using the command line instead. Neverthelss, I will mention three.

• TortoiseSVN For Windows

• Subclipse For Eclipse IDE

• Netbeans contains a Subversion integration module

Subversion Red Book

Version Control with Subversion.

Collins-Sussman, Ben and Brian W. Fitzpatrick and C. Michael Pilato. http://svnbook.red-bean.com/

Example: Adding a New Folder

This example uses the PowerShell. Mac users usually use their Terminal shell instead. Linux users usually use their bash shell instead.

• open a command shell (on Windows: Start > All Programs > Accessories > Command Prompt)

• use the cd command to change to the folder holding your working copy http://www.wikihow.com/Change-Directories-in-Command-Prompt

• you should always update before making changes, so ask Subversion to update your working copy by entering svn update

• use Subversion to create your personal directory by entering svn mkdir yourNewFolderName

• finally, ask Subversion to commit your new personal directory to the repository by entering svn commit -m "committing personal directory".

  note: the string folowing -m is just a message, but Subversion will require you to include a message when you commit.

Distributed Version Control

Subversion uses a centralized model for version control. Distributed version control systems (especially git) have become very popular. Each has advantages and disadvantages.

The arguments over the best approach continue:

• http://www.ianbicking.org/distributed-vs-centralized-scm.html

• http://www.developer.com/open/subversion-1.8-gits-new-features.html

Git

Git is a very popular alternative to Subversion, but it is somewhat more complex to use. For a discussion of how a git workflow is different, see:

http://blog.osteele.com/posts/2008/05/my-git-workflow/

Tracking Empty Folders in Git

You cannot: https://git.wiki.kernel.org/index.php/GitFaq#Can_I_add_empty_directories.3F

Directories are added automatically when adding files inside them.

If you really need an empty directory to exist in checkouts, create a .gitignore file in it. (You can leave it empty or specify files you want to ignore in the directory.)

Fixing Errors

If you do not follow the above instructions carefully, you may introduce errors. Most are recoverable.

Fixing Errors: warning W155007 (not a working copy)

You are probably trying to issue Subversion commands in a folder that is not under version control. Change directory into your project folder.

Fixing Errors: Skipped Paths

Probably you are just running svn in the wrong directory.

Otherwise, you may have created trouble by mishandling a merge. Uh oh. See http://stackoverflow.com/questions/3048662/svn-skipped-paths

Fixing Errors: Checksum Mismatch While Updating

Suppose version-controlled folder foo contains the file causing Checksum mismatch problems.

1. For safety, use your shell (not Subversion) to copy foo to another location (say, foo-copy).

Now that you are safely backed up, take the following steps, after changing directory to the foo folder.

1. Execute svn update --set-depth empty. (Note: this will delete all the folder’s files!)

2. Execute svn update --set-depth infinity

The first step will delete all the filed in the folder. The second step should restore all the files and fix the checksum problem by using the correct checksum information from the repository.

svn:ignore Folder Property

The svn status command reports unversioned files and directories in its default output. For some files and folders, this can be both useless cluttered. We can set the svn:global-ignores property or the svn:ignore property on any directory, which allow us to ignore files based on their names or extensions. While svn:global-ignores applies to all paths under the directory on which the property is set; svn:ignore applies only to the immediate children of the directory. For details, see http://svnbook.red-bean.com/en/1.8/svn.advanced.props.special.ignore.html

Projects often include an images folder for images that are generated by project code. The folder is under version control, so that all users have it. But the images themselves are not under version control, because they are generated files. The svn status command will display all the image files, with a question mark (?) to flag that they are not under version control. Listing these files is just clutter, so we would like to change this behavior. The svn:ignore folder property is useful for this. From the folder containing the images folder, enter the following (without the prompts).

svn propset svn:ignore "*.png
>> *.jpg
>> *.pdf" images

The >> prompts are supplied by Subversion, after each end-of-line. This process sets the svn:ignore property on the images folder, so that svn status completely ignores files matching these patterns. However, if you ever again want to see the full file listing, you can.

svn status --no-ignore

Locking

If the likelihood of conflicts becomes large enough for some files, users of a Subversion repository can agree to lock those files while working on them.

Here is some background: http://svnbook.red-bean.com/nightly/en/svn.advanced.locking.html

needs-lock File Property

Sometimes a file is under version control purely for reference, and it should not be changed. One way to signal this is to set its read-only file mode, using the svn:needs-lock file property. For example, if foo.txt is in the current working directory, we can set this property as follows:

svn propset svn:needs-lock ON foo.txt

Be aware that this does not completely forbid changing the file. There are two issues. First, some applications may simply override the read-only mode. Second, a user may set a lock on the file, at which point it becomes writable for that user. Upon unlocking, it again becomes read-only.

svn lock foo.txt -m "locked -> can edit"
svn unlock foo.txt

auto-props Property

You can use the svn:auto-props property to ensure that .nlogo files always use the Unix end-of-line convention. E.g., type the following three lines at your shell prompt.

svn propset svn:auto-props "
*.nlogo = svn:eol-style=LF
" .

Trunk

The trunk folder typically contains the current version of the project's non-experimental files. In a very small and simple project, most developers will work directly on a working copy of the trunk (which they check out to their personal computers).

Branches

Developers of bigger or more complex projects typically do not work directly on the trunk. Instead, they make a copy of the trunk in the branches folder, and do work on a working copy of this branch. So intially, a branch is just a subfolder of branches that stores a copy of trunk. It is worth emphasizing that this is an ordinary folder, which happens to be a subfolder of branches and happens to store a copy of trunk. Copying the entire trunk may sound expensive in terms of disk space, but Subversion cleverly does this in a way that uses new storage only to track actual changes.

It is most efficient to do this copying on the server. See http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html for details.

Teams may share a branch, or each individual may work on their own development branch. Once code is reviewed and tested on a branch, it can be merged back to the trunk.

Tags

Use the tags folder to create a snapshot of the trunk at a specific revision. Just as with a branch, this just copies this revision of trunk to a named subfolder of tags. Using the tags folder for this is purely convention, but you will confuse your teammates if you do not use this convention.

Additional Reading

An introduction to diffs and patches by Phil Estes

https://opensource.com/article/18/8/diffs-patches

Compare with git

https://www.git-tower.com/blog/git-for-subversion-users-cheat-sheet/

References

Copyright © 2016–2023 Alan G. Isaac. All rights reserved.

version:

2023-08-09