Skip to content

Developing With Git and Salesforce

Overview

This document describes how to use git and GitHub to work on a development task.

Before Starting on First Task

Install Tools

Install git, the force cli, and your preferred editor for Salesforce development.

Set up GitHub and Git

As a developer, you will push code to your own fork of the upstream salesforce repo and open pull requests against the master branch of the upstream repo.

  • Navigate to https://github.com/<organization>/salesforce and click on the Fork button to create your fork
  • From your fork's page, e.g. https://github.com/githubuser/salesforce, click on the Clone or download button and copy the URL. (HTTPS URLs are a little easier to get started with; refer to the github documentation if you want to use SSH.)
  • In your terminal, use the clone URL to clone your fork of the repo

$ git clone https://github.com/githubuser/salesforce.git - Add the upstream repo as an additional upstream remote. You are going to pull updates from upstream before starting on new tasks as described below.

git remote add upstream https://github.com/<organization>/salesforce.git

Each New Task: From New Branch to Pull Request

To work on a new task, you will create a new branch from the latest version of the upstream master branch, commit your changes to your branch, and open a pull request against upstream's master branch.

Pulling from GitHub

In your terminal, navigate to your local repository directory and pull any changes that have been merged into upstream's master branch.

$ cd /Your/Local/Repository/Directory
$ git checkout master
$ git pull --ff-only upstream master

The --ff-only flag will ensure that you can perform a fast-forward merge of the changes committed upstream to the master branch. If this fails, it means that your local master has diverged from upstream, which happens if you mistakenly commit to master rather than a development branch. If this happens, you can use git log upstream/master..master to identify the commits on your branch that do not exist upstream. If there are commits that need to be preserved, use git checkout -b to create a new branch, then checkout your master branch, and reset it to match upstream:

$ git checkout master
$ git fetch upstream
$ git reset --hard upstream/master

Creating a New Branch

Please review the [[branch naming convention|Standard-Practices#branch-naming]]. Once you have the new branch name, use the following command to create the branch (neglecting the brackets):

$ git checkout -b [name_of_your_new_branch]

Pushing Local Changes to Salesforce

If making changes locally with your text editor, you can deploy your changes to your sandbox with the following command:

$ force push -type [MetaData Type] -name [MetaData File Name]

Use force push --help for more options.

Making Changes Remotely

If making changes remotely within your sandbox, you can fetch your changes to your local directory with the following command:

$ force fetch -t [MetaData Type] -n [MetaData Name]

Committing Changes

To save your change progress, you commit changes in your local repository to your local branch. Please review how to write a good commit message. Use git status and git diff to review your changes, making sure you are committing the changes you intend to. Use git add to stage your changes, and git commit to commit them.

$ git status
$ git diff
$ git add -p
$ git commit
[write commit message and close editor]

git add -p is use to interactively stage your changes. This is a good way to review your changes while you stage them, and allows flexibility to commit only some of the changes in your working copy. You can use git add path/to/file ... to stage entire files or directories.

Pushing Branch to GitHub

Once your work is committed, you are ready to push the branch up to your fork on GitHub. Use the following command:

$ git push origin [name_of_your_branch]

Running Local Tests

To check if your development breaks any test classes locally, run the following command:

$ force test all

If your work causes any tests to fail, please work to resolve these issues before continuing. If they fail at this point, they will definitely fail at the pull request step.

Creating Pull Request

During development, you may make multiple commits that you push to your fork, but prior to opening a pull request, you should clean up the history on your branch. In most cases, your pull request should consist of a single commit. Your commit should have a [[well-written commit message|Standard-Practices#commit-messages]].

Clean up your history by rebasing against the latest version of master and squashing your commits.

$ git checkout master
$ git pull --ff-only upstream
$ git co XXXXX-my-dev-branch
$ git rebase -i master          (squash commits, clean up commit message)
$ git push -f origin            (if you rewrote history, you need to force push)

Once your work passes all test classes and is up to date on GitHub, create a Pull Request from your branch to the upstream Salesforce Master Branch. Creating the Pull Request automatically runs the test classes with the branch to spot any errors your branch would create if merged. Your pull request will then be code reviewed. If approved, the branch will be merged with upstream master branch, and automatically deployed to the full sandbox for further Quality Assurance.

Please comment with a link to your Pull Request on the Issue it resolves.

Wait for code review and merge, or comments upon the pull request. Once you've opened a pull request, treat the branch as "public", and don't rewrite history on it. Only add new commits to it. These commits can be squashed immediately prior to merging.

Before starting on your next task, check whether there are pull requests from other developers that [[need to be reviewed|Code Review]].

There is also a [[Pull Request Checklist]] you can review before opening a new pull request.

Closing a Pull Request

If you need to close a pull request, always include a comment about why it was closed. If the pull request is being replaced by a different pull request, include a reference to the new one in a comment.

Hotfixes

In cases where a hotfix is needed to be deployed to production prior to the next scheduled release, development is done on a new branch created from the last release branch, rather than off master. Otherwise, the development process is the same. For example, if the latest release deployed to production is 1.25:

$ git checkout release1.25
$ git pull --ff-only upstream/release-1.25
$ git checkout -b XXXX-my-dev-branch
[edit files]
$ git add -p
$ git commit
$ git push origin

After commiting your changes and pushing them to your fork, open a pull request against the release branch rather than against master.

Each hotfix will increase the tag's version hotfix increment by one (ex: v1.4.0>v1.4.1>...>v1.4.23).