For some time I’ve been using source control, predominantly for personal projects. The way I’ve used it has changed over time and is still changing.
There are a number of source control options, but the ones I’ve used are Mercurial and Git. Personally Git is my preferred option. That’s mainly because when I tried an existing database, I had to push it up in multiple chunks with Mercurial, but Git took the whole thing in one go.
For those not used to source control, there are three pieces in the puzzle:
Your NSF
This is where you (typically) do all your development.
Your on-disk project
This is basically a local backup of the database, not associated to any particular source control tool. It is created by right-clicking on the NSF in the Applications Navigator in the XPages Perspective and selecting Team Development > Set Up Source Control for this Application….
Never, ever, ever create this to an existing folder. It deletes all content in that folder before exporting the NSF. I always just accept the default. Linking to specific source control software will move it later to wherever required.
Also, I’d recommend disabling automatic import / export to the on disk project. This is done in Domino Designer Preferences, under Domino Designer > Source Control, with two checkboxes for import and export. The best way to think of this is that the on disk project is effectively a local replica of the database. If those preferences are checked, then it’s like after making any change to each design element, replicating to your local replica and waiting until the replication has completed before doing anything. It will have minimal impact if you’re working on local NSFs only. But if you’re working with server-based NSFs, we don’t need it, so disable it. All you have to do is get into the habit of manually syncing, by using Team Development > Sync with On Disk Project….
Your source control repository
Your on disk project can be accessed from the Package Explorer. The on disk project is turned into a source control repository by right-clicking on it and choosing Team > Share Project…. This is where the relevant source control plugin to Domino Designer comes in. The slight difficulty here is that Domino Designer is built on an old version of Eclipse, which limits the plugin versions and functionality available. Declan Lynch has nicely blogged the steps for installing the Mercurial plugin. For Git, it’s just a case of downloading the EGit for IBM Domino Designer from OpenNTF (thanks Nathan).
You can then choose which source control plugin to share the project via, to create the relevant repository.
Using A Source Control Tool
The plugins give the relevant functionality into Domino Designer to manage everything. But my preference up to now has been to manage source control synchronisation using standard Eclipse. Views in Eclipse may need refreshing, but you can easily pull your repository into Eclipse’s Git views.
Now for Git I’ve started using Source Tree, a free GUI tool for managing Git flows. It comes with an embedded Git and the install process is easy. Accessing your existing repositories from SourceTree is as easy as opening up Windows Explorer and dragging all folders in your Git Repositories folder into the navigation pane.
You can easily see what’s up-to-date, what’s staged or not, and compare changes easily.
One of the challenges of Git (and any source control tools not specifically designed for an NSF) is that Database Properties, Views and other design elements are identified as having changed when in material terms they have not. LastAccessed properties change, so the physical file is different, but not from a coding point of view.
I’m looking forward to seeing how Dora helps with that. Dora is a very promising project by Cameron Gregor that uses XSLT to filter the output DXL. It’s only just been released in beta, but is a welcome addition that has a lot of promise.
Another nice thing, there is also a SourceTree app for the Mac.
Great article Paul and thanks for the plug for Dora!
SourceTree also has support for Git-flow: a branching model that helps keep track of all the branches and workflows required for working with production code, new release code, bug fixes etc.:
http://nvie.com/posts/a-successful-git-branching-model/
I would love to have a Linux client too
Starting to use Source Tree with Xpages and Domino Designer. Been having strange behaviour with sync between nsf and on disk project.
When switching to newer branch with new design elements these are not synced between the on disk project and nsf. This requires me to do a refresh of the on disk version in package explorer and then team/sync with on disk project.
When moving back to an earlier branch with fewer design elements. I just have to do team / sync with on diisk project to make changes appear in nsf.
Anybody else having issues with this?
I tend to always refresh the ODP and then sync when switching branches. I did have a problem recently where there were changes in ODP but a sync didn’t pull them in. I haven’t had that before or since. But closing DDE and restarting solved it.
Confusingly, the EGIT page on OpenNTF says:
8<—- snip
DO NOT USE THIS PLUGIN. YOU DO NOT NEED IT. GO HERE INSTEAD…
https://www.atlassian.com/software/sourcetree/overview
8<—- snip
Can you please enlighten me?
Nathan and others have been using SourceTree for some time now for Domino development. It’s a much better user experience than using Git within Domino Designer, as well as supporting Mercurial. It also allows third-party diff tools like Perforce P4 Merge to give a better experience for merging. As a result, Nathan’s basically said on OpenNTF “don’t use EGit, instead use SourceTree”. I deliberately did a Show and Tell at IBM Connect 2014 as a resource for developers new to source control, so it’s worth looking at the slides for that https://www.intec.co.uk/show-103-source-control-an-end-to-end-solution/. The SourceTree bit is in the second half of the presentation.
Two other good reasons for using SourceTree are the ability to put multiple ODPs in a single repository and the ability to use third party merge tools like Perforce P4 merge.
A complete newbie to GIT Paul can you please clarify as I am confused with one point.
Using the Xpage Navigator I created the ODP. I have SourceTree installed.
I then went to share using Team > Share project and it came up with no options , ie no plugins. So I had to install EGit from OpenNTF.org to actually get a GiT repsoirory that SourceTree could work with and for Team > Share to actually show somthing I could select.
As the OpenNTF page suggests I shouldn’t need the EGit Plugin, but from my investigations so far it appears that SourceTree can not open an ODP directly or have I missed something
It sounds like you’re using the Package Explorer or something like that. The Team > Share Project option is a core Eclipse functionality, hence the need for the eGit plugin. The option you want is Team Development > Set Up Source Control For This Application from the Applications Navigator, but be aware that it’s only available in the XPages perspective (not Domino Designer perspective). Check out this NotesIn9, where I go into depth on using SourceTree with Domino Designer http://www.notesin9.com/2014/03/24/sourcetreedeepdive/