Add a Salesforce DX Project to Source Control

There are many version control systems and hosting services to choose from that help developers track changes to and collaborate on their code. DreamHouse Realty has chosen to use Git, a popular version control system, and GitHub, a popular hosting service for Git repositories. In this step you play the role of Chan Ming Lewis to add your Salesforce DX project to Git source control then share it with the team using GitHub.

Three computers syncing their local clone of a repository with GitHub

Create a GitHub Repository

You’ll need a GitHub repository to share your project with the DreamHouse Realty team.

  1. Sign in to or sign up for GitHub.
  2. Create a GitHub repository at
    • Enter sfdx-project for Repository Name.
    • Choose Public or Private access.
    • Deselect Initialize this repository with a README, Add .gitignore and Choose a license; we don't need these yet.
    • Click Create Repository


Confirm that your GitHub repository was created without any initial files such as a README, .gitignore, or license. A non-empty repository sometimes causes git merge conflicts that prevent people from pushing their changes in a later step. If your repository is not empty, delete it and re-create it ensuring not to add a README, .gitignore, or license.

Install Git

You need Git to add your project to source control and to upload it to GitHub.

  1. Install Git from
  2. Confirm the CLI is properly installed by running the following command.
    git --version
    You should see output like git version <versionnumber>.

Great, now let’s configure your Git identity and add your project to source control.

Configure Your Git Identity

Git uses a name and email address to identify commits with an author. In other words, this is how Git tracks which person is making changes to the project in source control. Your Git identity is not the same as your GitHub account, although both should use the same email address. You usually only need to configure your Git identity once per machine.

  1. Set your name to associate as the author of future Git commits. This should be your first and/or last name.
    git config --global "Your Name"
  2. Set your email address to associate as the author of future Git commits. This should be the email address you use with GitHub.
    git config --global ""

Create a Local Git Repository

Next, tell Git to track the Salesforce DX project, which is located in your sfdx-chan folder, in source control. Also tell Git to ignore files that don’t need to be versioned.

  1. In your sfdx-chanworking directory, initialize a local Git repository.
    git init
    You should see output like Initialized empty Git repository.
  2. In your sfdx-chan working directory, create if doesn't exist a file named .gitignoreand save the below contents into the file. Similar to .forceignore, which excludes files or directories from syncing between your local project and your Salesforce org, .gitignore excludes files from being added to your version control system.

Commit Your Files to Git

Next, tell Git which files to version then “save” them to your repository’s history. A typical development pattern is to edit files in your project, add the files you want to save using the git add command, and then take a snapshot of the file revisions using the git commit command.

  1. Add all files in the project to be tracked by Git (any files listed in .gitignorefile will be ignored).
    git add .
  2. Commit the added files as a snapshot to the project’s version history.
    git commit --message "Initial commit of DreamHouse metadata"

Push Your Files to GitHub

Up to now the Salesforce DX project only exists on your computer in the sfdx-chan folder. Let’s now upload the project to GitHub so that other DreamHouse Realty developers can collaborate on it.

  1. Link your local Git repository with your remote GitHub repository. Make sure to replace YOUR_GITHUB_USERNAMEwith your actual GitHub username.
    git remote add origin
  2. Push local commits (your file revisions) to the master branch on GitHub.
    git push origin master
  3. If prompted, enter your GitHub username and password. Git stores these in a Credential Manager so you are not prompted for them on every push. If you've enabled 2FA (Two-Factor Authentication), you'll need to enter a personal access token as your password.
    Git prompting for GitHub credentials to push changes


If you get the error remote: Repository not found when executing the git push command, confirm you’ve created the sfdx-project repository on GitHub and you’re using the correct URL with the git remote command.

If you get the error failed to push some refs when executing the git push command because the remote contains changes that you do not have locally, delete and re-create your GitHub repository ensuring not to add any initial files such as a README, .gitignore, or a license.

Good job. You’ve added your Salesforce DX project to source control and shared it on GitHub for the DreamHouse Realty developers to collaborate on. In the next steps you’ll play the role of Chan Ming Lewis and Maria Garza to develop new features and submit their revisions through GitHub pull requests.

We won't check any of your setup. Click Verify Step to go to the next step in the project.