Apple Generic Versioning (AGV) is a system that helps with software project version number management in Xcode projects. Adopting it has some benefits such as stamping the version information into the binaries in a way compatible with the what tool.

I thought about using it for my personal projects in the past, but was never comfortable with the agvtool utility manipulating files such as the Xcode project file directly. I thought that I would corrupt these files when I forgot to close the project in Xcode before bumping a version.

I’m now much more comfortable with that thought because I realized how well Xcode handles external changes to its open files. I realized that when I moved my projects to Git and started using local branches. At first I avoided switching between those branches while the project was open in Xcode for the same reason, but when I actually tested what happens when I switch back and forth I saw that Xcode handles it well:

Obviously you shouldn’t do this with files that have unsaved changes. Xcode seems to store all changes to the project settings to its project file right away, so you usually only have to check for unsaved source code files.

Now that I’m confident that I can’t get myself into trouble with agvtool (at least not this particular kind of trouble) here’s how I set it up:

First I enable AGV on the project level. There are two settings, setting the versioning system to AGV and setting the initial version number:

Make sure you set this on the project level and in “All Configurations.” There are some other settings on the target level, but Xcode should set those to sensible default values when you flip the switch to enable AGV.

Next I replace all occurrences of the project version number in the Info.plist file with a placeholder:

<key>CFBundleGetInfoString</key>
<string>Checksum version ${CURRENT_PROJECT_VERSION}, Copyright ...</string>
<key>CFBundleShortVersionString</key>
<string>Checksum version ${CURRENT_PROJECT_VERSION}</string>
<key>CFBundleVersion</key>
<string>${CURRENT_PROJECT_VERSION}</string>

From now on I can bump versions on the command line like this:

agvtool new-version 2.9

Xcode will display its “changed externally” message when it’s coming to the front again and after it reloads the project you can build with the new version number.

These two articles cover Xcode project versioning in much more detail, including alternatives to AGV:

http://www.dribin.org/dave/blog/archives/2006/08/02/versioning_os_x_apps/
http://chanson.livejournal.com/125568.html