Part of the Salesforce Admin Git & sf CLI series. Articles are standalone; read in any order. Foundation: Why Version Control · Environment Setup · Connect Your Org
TL;DR
- Version control is a history log for your org: every change is saved as a snapshot with a timestamp and author, and you can go back to any of them
- Git works perfectly with Salesforce because everything in Setup (Flows, Objects, Profiles, Page Layouts) is stored as files that git can track
- Setup gives you none of this: no history, no comparisons, no rollback. Git fills that gap entirely
What You'll Learn
- What version control is and why it matters for Salesforce admins
- How Salesforce stores your configuration as files (metadata)
- What git gives you that the Setup UI never will
- How to use version control to diagnose a real production problem
- How git and GitHub are different things (and why it matters)
The Problem: "Have You Ever..."
Have you ever changed a Flow and then couldn't remember what it looked like before you made that change?
Have you ever had a bug appear in production on a Friday afternoon (something is clearly broken, users are calling) and you had absolutely no idea what changed between Tuesday when things were fine and now?
Have you ever had two admins editing the same Page Layout in different sandboxes, deployed both, and ended up with one person's work silently overwriting the other's?
If any of those sound familiar, you've already run into the problem that version control solves.
Right now, when you change a Flow in Salesforce, that change just... happens. The old version is gone. There's no undo button beyond your own memory. If something breaks three days later, there's no built-in way to see what changed. You're left interviewing your colleagues, scrolling through deployment logs if you have them, or just poking at things and hoping.
That's the gap version control fills. Completely.
What Version Control Actually Is
Think about the "Track Changes" feature in Microsoft Word. When you turn it on, every edit is recorded: what was there before, what it was changed to, who made the change, and when. You can accept changes, reject them, or look back at the full history of a document.
Version control is exactly that concept, but applied to your entire Salesforce org.
Every time you save a change ("I added a new step to this Flow", "I updated the Opportunity page layout", "I changed the validation rule on Contact"), that change is recorded as a snapshot. That snapshot stores:
- What changed: the exact before and after, line by line
- When it changed: the precise date and time
- Who changed it: the person who saved the snapshot
- Why it changed: a short message you write explaining the reason
These snapshots stack up over time into a complete history of your org. You can scroll back through every change ever made, jump to any point in the past, and compare any two moments side by side.
The tool that manages all of this is called git. It was created in 2005 by Linus Torvalds (the same person who created Linux) and is now the most widely used version control system in the world. Virtually every software team uses it.
The snapshot in git is called a commit. Each commit is a permanent record that never goes away unless you explicitly delete it. You build up commits over time, and together they form the full story of your project.
What Salesforce Metadata Is
Here's the piece that makes git work so well with Salesforce: everything you configure in Setup is actually stored as files.
When you build a Flow, Salesforce stores it as an XML file. When you create a Custom Object, that's a set of XML files: one for the object itself, one for each field, one for each validation rule. Page Layouts, Profiles, Permission Sets, Apex classes, Lightning components: all files.
You don't normally see these files. You interact with them through the Setup UI: clicking, dragging, filling in forms. But underneath all of that, Salesforce is reading from and writing to files.
Git tracks files. That's its core job.
So when you pull your org's metadata down to your computer (which the Salesforce CLI makes easy, covered in Article 3), you end up with a folder full of those XML files. Git can then track every change to every file, giving you a complete history of your entire org configuration.
The type of files git will track for a typical Salesforce org:
| What you build in Setup | The file type git tracks |
|---|---|
| Flows | .flow-meta.xml |
| Custom Objects | .object-meta.xml |
| Fields | .field-meta.xml |
| Profiles | .profile-meta.xml |
| Permission Sets | .permissionset-meta.xml |
| Page Layouts | .layout-meta.xml |
| Validation Rules | Nested inside object files |
| Apex Classes | .cls + .cls-meta.xml |
If it lives in Setup, git can track it.
What Git Gives You That Setup Doesn't
Setup is a great tool for making changes. It is a very bad tool for understanding what has changed, when, or why. Git fills every one of those gaps.
1. Full history of every change
Every commit in git is permanently recorded. Six months from now you can look back and see every change that was ever made to your Lead object (who made it, when, and why) in chronological order. Setup gives you nothing like this. Once a change is saved, the previous state is gone.
2. Line-by-line comparison
Git can show you exactly what changed between any two points in time. Not just "this file was modified" but the actual before-and-after at the individual line level. For a Flow, this means you can see precisely which steps were added, removed, or changed. For a Profile, you can see exactly which permissions were granted or revoked. This is called a diff (short for difference) and it's one of the most powerful tools you'll use.
3. Rollback to any point
Because git stores every historical snapshot, you can restore any file to any previous state. Deployed a broken Flow to production? You can go back to the exact version from last Tuesday with a single command. Accidentally changed a Permission Set? Revert it instantly. No guessing, no recreating from memory. The old version is right there.
4. Audit trail with commit messages
Every commit includes a message written by the person who made it. Good teams write messages like "Added approval step for deals over $50K (per request from Sales Ops)" or "Fixed email alert on Opportunity: was firing for internal users". Over time this builds a searchable, human-readable history of every decision ever made in your org. When someone asks "why does this rule work this way?", the answer is often in the git history.
A Real Example: Tracing a Broken Flow
Let's make this concrete. Say you have an Order Management Flow that runs when an opportunity is closed-won. On Tuesday your team deploys some changes. On Friday, the sales team starts reporting that orders aren't being created correctly.
Without version control, here's your Friday afternoon:
You open the Flow in Setup. It looks... fine? Nothing obviously wrong. You start calling people. "Did anyone change the Flow?" "I don't think so?" "Maybe?" You check the deployment history if you keep records of it. You start manually re-tracing every step of the Flow looking for something that looks off. This takes hours, and there's no guarantee you'll find it.
With version control, here's your Friday afternoon:
You open your terminal and run a diff between today's version of the Flow file and Tuesday's version. Git shows you exactly what changed: two lines in the middle of the XML that control which record type the Flow fires for. Someone narrowed the trigger condition on Wednesday and didn't leave a note in Setup. With git, you can see the change, see who made it, read the commit message (if they wrote a good one), and either revert it immediately or understand what they intended and fix it properly.
Total diagnosis time: under five minutes.
That's the practical difference version control makes.
Frequently Asked Questions
Q: Do I need to know how to code to use git?
No. Git is a tool for tracking file changes, and it's used by writers, designers, data analysts, and plenty of non-developers. The commands involved in day-to-day git usage are straightforward. We cover them step by step in this series. You'll be running your first commit by the end of Article 3 without writing a single line of code.
Q: Will this break my org or change anything?
No. Setting up version control for your Salesforce org is entirely read-only from Salesforce's perspective. You're pulling copies of your metadata files down to your own computer and tracking them there. Nothing is pushed back into Salesforce unless you deliberately choose to deploy something. Your org runs exactly as it always has.
Q: What's the difference between git and GitHub?
This trips up a lot of people. Git is the tool: the software that runs on your computer and tracks file changes. It works completely offline and doesn't require the internet.
GitHub is a website: a cloud service that lets you store your git history online so your team can share it, back it up, and collaborate. There are other similar services (GitLab, Bitbucket, Azure Repos) that work the same way.
You need git. You don't technically need GitHub, but most teams use it or something like it because storing your history only on one person's laptop is risky. When we set up remotes in this series, we'll use GitHub.
Q: How long does it take to set up?
For a simple org, the initial setup takes about an hour: installing the tools, connecting to your org, and pulling your metadata for the first time. After that, incorporating git into your daily workflow adds maybe a few minutes per change. The time investment pays back the first time it saves you from a production incident.
Key Takeaways
- Version control is a time machine for your org: it records every change ever made so you can see what happened, when, and why, and go back to any point
- Salesforce stores everything as files: Flows, Objects, Profiles, and more are all XML files underneath the Setup UI, which means git can track all of them perfectly
- Setup has no history: once you save a change in Setup, the previous state is gone; git is the only way to get that history back
- Git and GitHub are separate things: git is the tool on your computer, GitHub is the cloud service for sharing; you need git first, GitHub comes later
What's Next?
The next article in this series is Setting Up Your Environment for Salesforce Development. It covers installing Visual Studio Code, the Salesforce CLI, and git itself: everything you need before you can connect to an org.
If you want to understand the problem before touching any tools, this article was the right place to start. Article 2 is where you start building.
Full series:
- Why Version Control: you're here
- Environment Setup: install VS Code, git, and the sf CLI
- Connect Your Org: authenticate with sf CLI and pull your metadata
Resources & References
- Salesforce Metadata API Developer Guide: official reference for all Salesforce metadata types
- Salesforce DX Developer Guide: Salesforce's own documentation for source-driven development
- Git Official Documentation: comprehensive reference for everything git
- Pro Git Book: free, complete book on git from the ground up; chapters 1–3 are all most admins will ever need
- Salesforce Well-Architected: Source-Driven Development: Salesforce's own guidance on why source control matters for org reliability