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 theClone 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).