TL;DR: "Build Automatically" and "Refresh automatically" are unrelated, but work together when both enabled when using SourceTree for source control.

I just had a conversation on Twitter where I went a little crazy talking about my hopefully-correct view of how the various sync processes in Designer work when you're dealing with source control.

The original impetus was a post by Mark Leusink about the fact that you have to build your NSF project in order to sync it with an on-disk-project (ODP) set up via Team Development. From there, that got into the topic of the "Refresh automatically" Eclipse setting that is helpful when using source control tools outside of Designer (e.g. SourceTree instead of eGit). The problem is that this stack of builders and settings is hard to get a hold of conceptually.

There are three "entities" to know about when it comes to how these things work together, along with a couple processes that can get your source code from one to the other. I tossed together this terrible image to visualize them:

I'll work from right to left, starting with the NSF. That part is nothing new, but the thing to know is how the NSF "knows" how to sync to an ODP. It's done via something called an Eclipse Builder. A Builder is a task you can attach to a project in Eclipse to do essentially arbitrary things when the build process happens for a project (or an individual part of a project). NSFs have a ton of them:

The one in question is the unnamed one at the top (don't ask me why it's nameless): that's the Builder that exports your changes from the NSF to the ODP. There's a companion Builder, also unnamed, in the ODP, that does the reverse when you make a change to the files there (normally you don't, but source control does). Because this sync is implemented with a Builder, it doesn't run automatically when you have "Build Automatically" disabled. Instead, it will run when you manually do a "Build All" or "Clean", or when you choose "Team Development" → "Sync with On-Disk Project" from the application list.

So the Builder handles all of the syncing between the ODP and the NSF. Where does "Refresh automatically" (which is very different from "Build Automatically") come in, and why has it only become a thing recently with the cultural shift away from eGit and towards SourceTree?

The culprit is the way Eclipse/DDE deals with the filesystem. Because OSes have traditionally been bad at notifying programs of when files change on disk, DDE doesn't actually know when a file is changed on disk. This is expected for something like an NSF (say, if someone else adds a view to an NSF you have open, it's no surprise that you have to refresh to see it in Designer (also, don't edit the same NSF from two places like that)), but counterintuitive with local files. The view of the ODP you see in Designer's Package Explorer is analogous to running an "ls" or "dir" command in the terminal and then adding a new file: the output from your command won't change until you run it again. What "Refresh automatically" does is attempt to keep its file listing up-to-date. Later versions of Eclipse modified this option to be more explicit and technical:

The upshot is that turning this on will (hopefully) keep the ODP in step with the filesystem. The chart I made is misleading here: the ODP and filesystem are technically the same storage area, but the ODP you see in DDE is really a listing of what Designer saw the last time it looked.

This is useful when using a tool like SourceTree to handle your source-control operations. Because DDE doesn't normally "know" about filesystem changes, you could update your local source repository from the server with tons of changes, but Designer wouldn't know until you kicked it. With "Refresh automatically", it should notice those changes on its own, update the ODP in Package Explorer, and, if "Build Automatically" is on, sync those changes into your NSF.

The reason this matters now and didn't/doesn't when using eGit is that, because eGit is an Eclipse plugin and does its filesystem access through Eclipse, Designer already knows when a source-control-related operation changes files on the filesystem: since it made the change, it doesn't need to refresh. So if you're using an Eclipse plugin for source control and not editing files on the filesystem manually, you can remain in blissful ignorance about "Refresh automatically."

I think it's fair to say that most professional programmers know that they should use source control, but, unless you work for a company that mandates it, you treat it like flossing or going to the gym. However, unlike your personal health and well-being, using source control is very important and can improve your life noticeably.

I'm a recent convert, in part due to Domino's historic hostility to proper source control. However, since 8.5.3 and its inclusion of the surprisingly good Source Control Enablement, there's no more excuse to slack. If you haven't already, read/watch the following things (and shame on you):

• Notes in 9 #41: XPages, Domino Designer and Source Control! Part 1
• Notes in 9 #44: Using Source Control Part 2
• Keith Strickland: Source Control in Domino Designer
• Keith Strickland: Source Control in Domino Designer Part Deux
• Keith Strickland: Source Control in Domino Designer - Branching

But beyond the basics of "make sure to check in changes with useful notes", I want to figure out the best way to do Domino development in this brave new source-controlled world. Mainly, I think I'm going to try to adopt a model similar to a shipping application: longstanding "write once" branches for significant versions, lengthy but temporary branches for development of the next version, throwaway branches for pie-in-the-sky ideas (like whenever I want to try to re-do my forum app's data access layer), and deployment via Source Control Enablement's "New Database From..." functionality.

That last part is huge, especially now that it's so easy to point an XPage app to a different database for its data access. I'm going to try more of an app/data separation in the future - I'm not sure I'll stick with it, but I think it could be very useful in deploying a new just-about-live version of an app alongside the "real" live one.

Regardless of the specific form my development process takes, I'm aiming to integrate source control thoroughly, to the point where NOT using source control feels "dirty", the same way that modifying a production app directly does. Fortunately, it doesn't take much to reach that point - just one instance of a client asking "is there any way we can go back to how it was working at the start of the week?" and being able to do it and you'll never look back.