Version Control

When you develop software, you should use version control. Cordova projects are no different. Using version control offers a number of distinct benefits. With version control, you can:

• share code easily with other developers.
• know exactly what version of each file in your codebase you have deployed, which is extremely helpful when debugging issues.
• roll back mistakes.
• move code between machines.
• check out a fresh version of the code and know exactly how to build the project in a replicable fashion.

Version controlling Cordova projects is fairly similar to version controlling other web development projects. However, the Cordova CLI generates some artifacts that should be excluded.

What to Version Control

After you run cordova create sample-cordova-project, a Cordova project has these directories in the project:

• www: your application’s HTML, CSS and JavaScript files
• merges: platform specific HTML, CSS and JavaScript files
• .cordova: ‘under the hood’ cordova files and directories, as well as lifecycle hook scripts
• platforms: platform specific build directories
• plugins: plugins added via cordova plugin add

The www, merges, and .cordova directories should be versioned, and the platforms and plugins directories should not. Add the platforms and plugins directories to your version control system’s ignore file.

There is also a .cordova directory in your home directory that you should not version control. It does have an impact on your project–it’s where the global Cordova libraries are kept–but it should be entirely managed by Cordova CLI and you can safely ignore it.

You are not limited to the above five directories. You can add additional directories in your project should you require them. A common additional top level directory would be test, to hold your unit tests. Such directories will be ignored by the Cordova CLI.

You can use all the features of your version control system, just as you would with any web development projects. Tags, branching, merges, etc, are all fair game. Version control meta directories like CVS and .svn are copied from the www directory to the platform www directories when you build. Therefore, someone decompiling your application may have access to your internal directory structure. (You can use a hook to clean up the meta directories, though.)

The plugins directory is typically empty until you add a plugin. Some version control systems don’t create empty directories. If you add a plugin but the plugins directory is not present, you’ll receive an error.

1 $ cordova platform add android
2 { [Error: ENOENT, no such file or directory '/path/to/rootdir/sample-cordova-application/p\
3 lugins/android.json']
4   errno: 34,
5   code: 'ENOENT',
6   path: '/path/to/rootdir/sample-cordova-application/plugins/android.json',
7   syscall: 'open' }

Limits of Version Control

Not everything in a production Cordova application can be version controlled. Larger environment components like your platform specific SDK can’t be easily version controlled, though if you are using virtual machines, you can use vagrant and setup scripts to attempt this.

In addition, there are some IDE settings, especially when releasing, that can’t be version controlled. Building for IOS in XCode, in particular, has some arcane build settings and processes that require use of the IDE to release. There are also Cordova bugs that are worked around through editing build settings in the IDE. When I can’t version control key project configuration like IDE settings, I do the next best thing–document them well.