I'm unsure what is best practice for storing my sfdx projects in git repos. Do I store each project in one repo, or can I store multiple projects in one repo?

This is what I'm thinking it should be

├── GitRepoName  //aka "Source of Truth"
│   └── Project1 // aka "Artifact" aka "sfdx project"
│   └── Project2 // aka "Artifact" aka "sfdx project"
│   └── Project3 // aka "Artifact" aka "sfdx project"

I'm not super savvy with git yet, but I would think once I created a new scratch org, I could push each artifact into the scratch org by switching directories and using sfdx force:apex:source:push.

It appears to me that things could be difficult if I'm switching between projects, with say Project1, 2, 3, in the scratch org, and I do sfdx force:source:pull in my Project1, it could also pull the source that came from Projects 2 & 3, right?

  • 2
    We don't use markdown here. I've fixed your post for you. Use the code format button in the future. – sfdcfox Feb 28 '18 at 1:11
  • @sfdcfox you mean "We don't use fenced code blocks here." You do use markdown. – Charles Koppelman Jun 14 '18 at 20:33
  • @CharlesKoppelman It's like ... Markdown Lite. It's not the same that you'd use on GitHub and elsewhere. You're right, though, it is a flavor of Markdown. – sfdcfox Jun 14 '18 at 20:34
  • if I'm creating an official scratch org definition file for my team as recommended here should I force it into my other SFDX Project / repos via Git submodule? – bkwdesign Jul 11 at 16:59

Read the answers on What's the best practice for putting multiple projects in a git repository? for some possible solutions (over on Stack Overflow). My biggest concern is that if you end up screwing up something in one of the projects, and you try to fix it, you might end up reversing changes in other projects by accident. If you do decide to follow the path of multiple projects in a single repo, consider using "orphan branches", which will help isolate accidental destructive changes. There's details in the answer linked above and also on git-checkout, look for the --orphan option.

In my personal opinion, you would be better off with separate repositories, because it avoids the possibility that you'll merge something into something else that you didn't mean to do, which can cause an absolute mess of things. While it's "easy" to clean up most mistakes, merging two entire projects together might result in a lot of downstream messes, since you'll basically be forced to backtrack and rebase. Every developer depending on your repo will be forced to undo all their work and clone the repository fresh to avoid any lingering mixups. You don't want this to happen.

Keep in mind, too, that a git repo essentially contains every copy of every change ever committed to the repo when you clone or pull; obviously, this is not literally the case in terms of disk space, but it does make the cloning process longer. This may make clones and pulls more painful than they need to be in terms of processing time. There's other ways of dealing with this, but simply having one repository per project makes that management trivial.

Also, git servers do tend to have an absolute maximum repository size. You'll reach this size sooner if you have multiple, active projects all going at once in the same repository. It might not matter with just Apex Code and Lightning, but if you've got a lot of heavy duty files (data load files, static resources, documents, attachments, etc), you'll exhaust your limits faster than you would with separate repositories.

Note that sfdx uses a project configuration file to pull source. So if you have project1, project2, and project3, and you're in project1's directory, you'll pull the contents of project1 into it, but not project2 or project3. However, if you screw up a username/alias even once, you'll end up having to reset/clean your repository and you'll risk losing work in the scratch org. The last thing you want to do is have a major conflict of (for example) 2,000 files and have to try and manually resolve it.


With the advent of 2nd Generation Packaging and Developer Controller Packages with SalesforceDX; Salesforce is telling us to break a project into related components called artifacts.

These artifacts/DCP's can be stored, versioned and released independently.

To answer your question, let's take an example :

All the source-code for project 1 resides in



Once you break it up into some logical artifacts it could look like


Now, you can define their inter-dependency, if any in the sfdx-project.json like before installing chatBot, main package must be deployed to scratch org first and which version number should be deployed. See more settings here.

So this is how your Git repository should be shaped. Each repo having one SFDX project and that SFDX project could have multiple artifacts.

To push these packages in the scratch org, you need to push them using packaging 2 commands.

sfdx force:package:install -i 04t... --targetusername jdoe@example.com

See the Salesforce Documentation for more commands.

Checkout, Salesforce's DreamHouse app's repo to view the structure and specifically the pkg-2 branch's sfdx-project.json over here.

Also, see my another answer where I've posted a sample sfdx-project.json with dependencies.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.