Salesforce – Iteration Zero: How to Place an Org Under Source Control

You need an audit trail if you want to be able to see what has changed in either configuration or code.  A source control system such as Git can provide this audit trail.  The default out of the box Salesforce experience only tells you who made the last change and when, not a full history.  I’ll show you how to pull all of the configuration data and code; then how to place these files into a repository.  Now you will have an audit trail going back further than just the last change and on top of that actually get to see what specifically changed.

Clicks not Code

If you haven’t experienced working with a team of people writing code, then you may not have experienced this need for source control, but trust me you need it.  Without it understanding what has changed in the system is just too difficult and error prone.  Imagine a frustrated client with a production instance that is not working as intended and you are unable to answer the first question “what changed”.  Source control is similar to Microsoft Word Tracking, only much, much better.

Glossary and Tools

Git: Git is a source control system.  There are others out there but in my opinion this is the best-of-breed.  Your company may have a system already in place, or you may be using one of the popular providers BitBucket or GitHub.  I’ll use BitBucket for this.  GitHub requires that any repositories created with a free account be open-source.  Not BitBucket, heck they even allow you to invite 4 of your colleagues or friends to collaborate on code.  Beyond the free trail, prices are very reasonable: about $1/user/month.  GitHub is also very reasonable and they have some features that BitBucket doesn’t such as Gist.

SourceTree: This is a tool that makes working with Git easier.  If you selected GitHub as your server repository there is a similar tool out there called GitHub Desktop.  Because you’re running Git commands and interacting with a Git repository, either tool will work with the others server instance. IDE: The default development environment for Salesforce is Eclipse with a plugin written by Salesforce.  You have several other options, the most popular being MavensMate.


Skip if you already have the tools mentioned above installed


  1. Create the repository out on the BitBucket server.  In Git terms this is called a remote because it doesn’t reside on your machine.  It’s easier to create an empty repository on the server and then clone it to our local machine rather than work in the other direction.  You can take a look at the repository I created for this blog at IterationZero.
  2. Clone the repository to your local machine.  The server repository is just an empty container where we are going to store files which are then versioned every time we commit a change.  The clone operation is just creating a copy of the container and some internal files that support the versioning system, and most importantly creates a relationship between your machine and the remote.
    View the repository we created in step 1 and copy the https address in the upper right corner.  Open SourceTree and click the Clone button.  Paste the address into the source path / url input and specify where you want the local repository (C:\blog) and give it a name (IterationZero).  After clicking clone you now have the same empty container on your local machine. steve 1
  3. Pull all metadata from your Salesforce org to your local machine using the IDE
    1. Switch or create a workspace, set the workspace to the same folder as the local repository created in step 2 (c:\blog)
    2. From Eclipse, File \ New \ Project… \ \ Project
    3. Use the same name (IterationZero) and enter your credentials
    4. Next you’ll be prompted to select metadata components, let’s pull everything that we cansteve 2
    5. Here’s what the resulting folder structure looks likesteve 3
  4. Initial commit to BitBucket.  If SourceTree is still open you’ll see a large number of files in the unstaged panel.  We don’t want to capture the content of the .metadata folder, so right click on the first file, select ignore and change the criteria to ‘ignore everything beneath .metadata’.  Also ignore the .gitignore file.  Click ‘Stage All’, add a message, check ‘Push changes immediately to -‘ and click Commit.  You’ll be prompted for your BitBucket credentials.  This action just created an initial version of your org on both your local machine and on the BitBucket server.
Rinse and Repeat
  1. Make changes in either the code base, or through the admin UI.  For this demo I have added a custom field to the Opportunity object.
  1. In the Eclipse IDE I can right click on the project in package explorer, select \ Refresh from Server.  This will refresh my local copy of the org metadata. 
  2. I left SourceTree open so it was able to detect the file changes and a number of files were changed.  I can review these changes, and if they are all intentional, I’ll stage them, add a commit message, check push changes immediately to origin/master and click the Commit button.
  3. I now have an audit trail, I can see what exactly changed, when and by whom.  Anyone with access to the repository can view the audit trail.steve 4
  4. When viewing source the Blame feature shows you the current version of the file where you can see who performed the last edit and when line by line
About the Author

Steve MunLeeuw is a certified Platform Developer at Statera with two years of CRM development experience.  Prior to working on the Salesforce platform he specialized in integration work with JBoss Fuse and worked with C# since it’s inception.  When not coding he likes to explore dirt roads and watch live music.