Setting up Eclipse, and making your first commit to Stash
This guide is part of my ‘How to set up Continuous Integration for Salesforce.com’ series of posts, and will take you through configuring Eclipse, SourceTree and Stash for your first commit.
This tutorial requires the below pre-requisites. In reality there are many other tools that can be used, but these are the ones that I am most familiar with:
- For Force.com development on your local machine, you have Eclipse installed with the Force.com IDE (see ‘Force.com IDE Installation Instructions‘).
- For Source Control Repository software you have Stash installed and running on AWS.
- To help integrate your local code with the main repository you have Atlassian SourceTree installed on your machine.
1. Setup a repository in Stash and connect it to your local machine
1.1 – Open your Stash instance, and select ‘Create Project’. Once saved, click on the project and select ‘Create Repository’. The project is empty, but you now have somewhere to store your files. In the below screenshot, my project is ‘Salesforce’, and my repo is ‘mySalesforceOrg’.
1.2 – Click on the project in your browser, and select ‘Clone’ in the top right of the screen. Then select ‘Clone in SourceTree’ – this will open SourceTree on your local machine, and default in the URL of the Stash repository.
1.3 – In the “Destination Path” choose a new folder that you will later re-use to make your changes in Eclipse. This folder will be location that your Salesforce code will be saved/edited/updated in later steps.
2. Setting up an Eclipse Project to use SourceTree
2.1 – Open Eclipse and select ‘File -> New -> Project’. Use the standard project wizard too – do not select a ‘Force.com Project’ yet – we only want to create a project linked to SourceTree – we don’t want to add Salesforce files yet.
2.2 – In the navigator, you should see your new project appear, but clicking on it, you will see there is nothing in it yet.
2.3 – Next, we want to add an example file so that we can commit the change to Stash, via SourceTree (thus testing the overall committing process). To do this, right click on your project in the Navigator, and select ‘New -> File’. Enter a test file name (I used ‘SourceTreeTest’) and hit ‘Finish’.
2.4 – Double-click on your new file to open it, enter some random text, and then hit ‘Save’.
2.5 – Now, return to your running SourceTree instance, and open your ‘ciTutorial’ repository that you set up earlier. The expected behaviour at this point is that SourceTree should automatically identify that you have made a change in the project workspace, as below:
3 – Making your first commit to Stash
3.1 – Now, we will make our first commit to Stash. To do this, click and drag the files you want to commit to Stash from the ‘Working Tree’ directory and into the staging area directly above it. This prepares your files to be committed.
3.2 – With the items selected in the staging area, click on the ‘Commit’ button (see top right). This will load a page where you confirm the commit you want to make.
There are two important things to note here (below). When you are ready click ‘Commit’.
- As a committer you should enter a meaningful description, including any ticket references or IDs so that other users can track changes to work items and have access to a proper audit trail.
- ‘Push commits immediately to: origin’ must be selected in order to push to Stash. Else the commit will remain on your local machine only.
3.3 – SourceTree will be updated as soon as your have made your commit. You will see that a ‘master’ branch has been created, with your first commit. ‘origin/master’ refers to the new master branch in Stash, whilst ‘master’ is referring to the ‘master’ branch on your local machine.
Going forward, all commits made this way will add extra notches to this graph, and it will begin to build out over time, with a full audit trail available to any user.
How does this work?
Stash is the shared code repository available in the cloud, which can be used to make your source code available to other developers as well as automated deployment systems such as Bamboo. The use of these tools will be covered in later tutorials
SourceTree sets up and runs a local git instance on your machine, in a folder of your choosing. It tracks changes in your local folders in the same way that Stash, GitHub or any other Source Control system does. So, when you save a change to that folder, it knows about it.
In this tutorial Eclipse is being used primarily to save a file to the SourceTree folder. You could also copy / paste files into the SourceTree folder using Windows or Mac file explorers to achieve the same results.
In this example we created a standard Eclipse project and not a Force.com project – in the next tutorial, we will ‘Add a Force.com Nature’ to this project, and download the Salesforce.com codebase. The connection that we set up to SourceTree in this tutorial will be used to commit a much bigger set of files then.
- Intro to Git with SourceTree (Video)
- SourceTree and Git – How to make a commit (Video)
- SourceTree FAQ