XPages site addressing modern Domino

Using Git in Domino Designer 8.5.3 and above

Git is a distributed source control repository.  The other similar solutions are Mercurial, Bazaar, or Darcs.  I prefer to use Git for my source code solution because that is what the Linux Kernel and most other non Domino Open Source development projects use.  Nathan Freeman has done a excellent job porting eGit to Domino Designer.  eGit is a Eclipse plugin for Git.

At a high level, this is what you’ll need to do:

  1. Install Git onto your Windows PC
  2. Install the eclipse eGit plugin into Domino Designer.
  3. Configure Git
  4. Create a on-disk representation of your NSF (extracting your NSF to the file system)
  5. Share the on-disk representation (have Git manage the source, a repository will be created in yet another location.

After completing these steps you can then start developing.  Your new development process will be slightly different.  You will development in your NSF like you normally wood, when you reached a milestone then using Git command line to commit your changes into your repository.  You may also use eGit’s context menu or tool bar to do the same thing.  I find the command line gives more more control over what is happening behind the scenes and its quicker because you complete more actions in one place quicker.

Committing is taking a snapshot and putting that snap shot into your local repository.  Then you optionally push your changes to a remote repository.  Branching is a little more advanced, first get your head around working local, then start learning to branch off the master repository and work in teams with other developers.

You can download a presentation to accommodate this post.

Install Git

Download and install Git

I recommend during the install to include the Unix tools during the installation process.  Use recommended settings for all other options.  After your install, you should have a book mark on your Task Bar.


Install Eclipse Plug-in eGit

Step1: download the installation zip file.  (org.openntf.egit.update.zip)

Step 2: Open Designer.  Click File -> Application -> Install.  A dialog box will pop up, keep the second option “Search for new features to install”.  Click Next.

NOTE: If you don’t have the Install option, then you need to open Preferences and enable it.  The setting is under the Domino Designer section.  The setting is called “Enable Eclipse plug-in install”.

Step 3: In the Application Locations dialog box, click Add Zip/jar Location button, browse and select the zip file you downloaded in step 1.  You come back to the dialog box, and make sure only org.openntf.egit.update.zip is checked.  Click “Finish”.


Step 4: This brings you to another dialog “Updates”, select org.openntf.egit.update.zip.  Then click Next.  Accept the license agreement then click Next.  Then you have to click Finish to install.  You’ll get a warning that the plugin is not signed.  Go ahead and select the “Install this plug-in” radio option and click OK.



NOTE: There are more screens after this one, so just pwdkeep moving along.  When you installed eGit Successfully, you will be prompted to restart the client.


Configuring Git and your environment

At this point you have all the software you need installed.  Now lets do some configuration steps.  Open the Git Shell.  It should open in your home directory.  Create a folder called src.  This is you source folder for all your development projects.  From that folder you can create folders for any development project from static web sites, Java applications, iOS Native applications to IBM Notes XPages Applications.  The folder src means nothing to git, this is only our root folder to organize our projects.

NOTE: This configuration is only done once and these settings survive future upgrades.

Your Identity

In the Git command shell, enter:

$ git config --global user.name "Your Name"
$ git config --global user.email "Your Name @yourdomain.com"

These config settings are strictly used for logging purposes and these will not be used for authentication.

Leave your shell open, and switch to IBM Domino Designer.

Source control with a .NSF

Open a Notes Application in Domino Designer or create a new one.

Right click on the Notes application and select “Team Development -> Setup Source Control for this application”.  A dialog box will pop up, you’ll need to click Next.  Enter a project name in the next screen then click Finish.  This will extract your .NSF into a folder on your local file system.

gitNSFDemo-1 gitNSFDemo-2 gitNSFDemo-3

Eclipse will create the association between the .NSF and on disk representation.  If you make a change in either the .NSF or the on disk representation, the eclipse IDE will refresh automatically.

The IBM Domino Designer should have opened the Navigator Eclipse view.  If it did not, you’ll need to open it

Window->Show Eclipse Views->Navigator.

Using Navigator, right click on the “On-Disk Representation” and choose Team -> Share Project

A dialog box will pop up, Configure Git Repository.  Make sure you uncheck “Use or create repository in parent folder of project”.  There is a “Create” button next to a drop down field for repository.  Click Create.   This create creates an empty folder in the git repository located in $Home\src\git-demo.

Another popup will be presented asking for the project name, this is going to be the folder created in src.  You should avoid using spaces in the name.  Click Finish.

gitNSFDemo-4 gitNSFDemo-5 gitNSFDemo-6


After clicking Finish, check the Git repository status again


You project is not tracked by default.  You could get granular and only track changes to one design element if you like.

In our demo, we want to track all changes.  So lets tell Git to start tracking everything.

$ git add --all
$ git status
$ git commit -am "First Commit"

The -am switch tells Git to commit all modified and new files. If your working in a team, and you someone needs a completed Stylesheet only, you can commit just the style sheet. The ‘m’ means “Commit Message”, this is the message that shows up in Git logs. You want to be descriptive as possible. Please don’t commit with comments like “It’s bed, good night”. That doesn’t help anyone later when we need to locate a specific change.

Make your first commit

Now your ready to make your first commit.  When you make a commit, that tells Git to create a snapshot.  Keep in mind, anything committed is always recoverable.  If you lose work and never committed it into the repository, its gone forever.  Think of committing like snapping a picture with a camera, and every other commit is yet another snapshot creating layers before you actually push your changes.  Usually developers make a change, commit then push right away before their next commit.

Make some changes to your NSF, add a form for testing.

Launch Git command line, I have it pinned on my task bar “C:\Program Files (x86)\Git\bin\sh.exe” –login -i

Git launches into the root of your repository.  You’ll want to change directory into the project directory.  This is the project name you chose when sharing your on-disk representation.

When you in the command line window type in:

$ git status

# On branch master
# Untracked files:
#   (use “git add <file>…” to include in what will be committed)
#       projectFinal/Forms/frmTest.form
nothing added to commit but untracked files present (use “git add” to track)

Looking at the output, git is telling you you have one untracked file.  You’ll want to add the file so it can be tracked.  Untracked files are not pushed or committed into the repository.

$ git add --all

slohja@xpagesbeast /c/users/slohja/src/projectFinal (master)
$ git status
# On branch master
# Changes to be committed:
#   (use “git reset HEAD <file>…” to unstage)
#       new file:   projectFinal/Forms/frmTest.form
slohja@xpagesbeast /c/users/slohja/src/projectFinal (master)

Now the form is listed under the “Changes to be committed” category.  Lets commit the change.

$ git commit -am "Added the projectFinal Form"
[master cb61164] add frmTest
1 file changed, 31 insertions(+)
create mode 100644 projectFinal/Forms/frmTest.form
slohja@xpagesbeast /c/users/slohja/src/projectFinal (master)

Your changes are now committed, you can verify by doing a git status again.

$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#   (use "git push" to publish your local commits)
nothing to commit, working directory clean
slohja@xpagesbeast /c/users/slohja/src/projectFinal (master)

You should get a message “nothing to commit”.

If you want to learn more, type in git –help to see all the commands available.

$ git --help


To be continued ….