Stop documenting. Start versioning with Git.

If you're making a change to an important workflow in Salesforce while in San Francisco, how do your New York colleagues know?

Well, they can check the logs, which likely only offer limited information. It may say something like, “So and so made an unspecified change,” meaning they still won’t know what change you made or why you made it. And if you have, say, 125 Salesforce admins globally, 7,000 salespeople, and however many other systems that are all making changes in Salesforce, how on earth does any individual know what’s changing and why?

That’s where version control comes in.

Versioning with Git is part of an exciting change rippling through the business operations field, where admins are increasingly borrowing tools that have proven successful in other disciplines to help mature and elevate the practice. Software engineers have long relied on versioning to improve collaboration and enhance their code. In this article, we’ll explore what Git is, why it’s so important, and how you can use it to do your job better. Let’s Git—er, get into it.

A short history of Git

Git is free and open-source software, developed in 2005 by Linus Torvalds—the main developer behind the Linux operating system (Linus, Linux, get it?). It essentially acts as a time machine for text files. With Git, you can go back through your version history, viewing snapshots called “commits” that show you your project along each stage of its development (we’ll break these down in more detail in the next section).

Git was not the first version-control software. It was predated by other similar tools, such as BitKeeper, which the Linux Foundation (then called Open Source Development Labs) had been using until fears around copyright infringement caused BitKeeper to withdraw Linux’s free license. This spurred Linux to develop its own free open-source version—and Git was born.

Before Git, older version control systems were hosted on a single server. You can think of them like a library. When developers wanted to edit a section of the code, they’d have to “check out” that particular file, as though it were a book. The central repository would lock that file and prevent anyone from “borrowing” it until it was returned. This ensured developers didn’t inadvertently introduce conflicts into the code, but also meant that only one person could work on any given section at a time.

Git, on the other hand, is totally distributed. Each user has access to the full “library” at all times and can edit any part of the code they want. The way this works is through Git’s branching feature—this enables users to work in their own isolated copies without affecting the source code. This means multiple users can work on the same section of code at once and conflicts are managed when the different versions are brought together, or merged, onto the main line of code. Today, Git is the most popular version-control system in the world. It’s used by the likes of Google, Facebook, Microsoft, Netflix, Twitter, and more. GitHub, an online service for developers using Git, boasts 73 million users across four million organizations. (For clarity, Git is the name of the free open-source software, whereas GitHub is a site that developers using Git can connect to, in order to share resources with other developers.)

As for where the name “Git” comes from, the README section of the code offers a few humorous suggestions:
‍

Noting that “git” is British slang for an unpleasant person, Torvalds once famously quipped, "I'm an egotistical bastard, and I name all my projects after myself.”
‍
‍‍

Why is Git important for admins?

Git helps teams work more efficiently, collaborate better, and prevent the sort of human error that can lead to catastrophic system failures. Git tracks every change made by every contributor, so it’s easy to understand what’s changed, why it’s changed, and if necessary, revert to a prior version.

Where this can have the most impact for business systems operators is in the realm of documentation—which is great and very necessary—it helps us maintain order and a clear history, especially for compliance purposes. However, many business systems teams are still relying on external documents or spreadsheets to manage their documentation, which is at best inefficient and at worst could be harming your team.

Here are some of the key drawbacks of managing your documentation in external documents:
‍‍

• Poor Discoverability - It can be challenging to locate the right documents at the right time
  
• Documents falling out of date - The high pace of change makes it difficult, if not impossible, to maintain up-to-date documents
• Compliance challenges - Figuring out who altered what, where, and why, causes major headaches with every audit

Git is a more streamlined way to create documentation than maintaining external documents or spreadsheets. Instead of happening on the outside, it allows you to manage your documentation right inside your business systems.

And it makes collaboration easier too. As previously noted, Git’s branching system allows contributors to edit the same section of code without affecting each other, or any of your core business systems, and only merge it back when you’re absolutely sure it’s ready to deploy. This enables your team to work in faster cycles, improves the success of your changes, and protects your systems from unintentional catastrophe.
‍‍

1. The commit message subject - A single line describing the change in a way that'll capture the main gist, making it a breeze to Review a list of changes quickly.
2. The commit message body - Free text where you can elaborate more on the change, allowing whoever reads the commit message in the future to drill down as needed.
   ‍

How to use Git

Ready to get into Git? Here’s how to get started in just a few easy steps. All you need is a computer and internet access—no coding experience required.
‍
1. Create an account on GitHub (it’s free)
‍
All you’ll need to sign up is a username and password. Do be mindful of what username you choose—any changes you make will be credited to it. (If you plan to use Git for work, you might want to use your real name, rather than, say, corgi_lover27. But we’ll leave that to your personal discretion.)

2. Create your first repository (‘repo’)
‍
Once you’re signed in to your shiny new GitHub account, click the [+] symbol on the right-hand side of the top nav, and click “New repository.”
‍

Enter a name for your repository (GitHub recommends “hello-world” but you can name it whatever you like). Write a description for your repository, mark it as public or private, and be sure to check the box that says “Add a README file”—this is a file with information on your project, written in Markdown language (a form of syntax that allows you to format plain text documents).

README files are important because they provide an introduction and orientation to the material in the repository (remember Git’s README file explaining its purpose and where its name came from?). This prevents your collaborators from having to read your mind when they join you to collaborate on a project.
‍

Once you’re ready, hit the button that says “Create repository.” That’s it—you’ve just created your first repo.

3. Create a branch
‍
Here’s where versioning comes in. Branching is the functionality that allows you to maintain different versions of your repository at the same time—which is extremely useful for collaboration, change management, or just when you want to play around and experiment without affecting your core systems.

By default, GitHub starts you off with a branch called “main”—this is considered the definitive version of your repository. You can create multiple versions by creating new branches off the main branch.

To create a branch, click on the Code tab of the repository you just created. Select “main” from the drop-down list and enter a new branch name into the text box.
‍

Click “Create branch.” You should now have two branches, your main branch, and a second one with the name you chose.

4. Make your first commit
‍
So you now have two branches, but they’re still exactly the same—which means it’s time to create your first commit.

What’s a commit, you might ask? Great question! A commit is a saved change in Git—it includes text differences, a timestamp and author associated with the change, and a message from the author. Think of it as a snapshot of your work, with a caption explaining exactly what the viewer is looking at.

Ready to make a change? When you created your repo, you already added a README file to it, so let’s start there. Click on your README file, then click the pencil icon to edit. You can write whatever you like—introduce yourself or write a short description of your project. Be sure to use Markdown language to format your writing properly (here’s a cheat sheet for Markdown language). When you’re all done, you can preview your changes to make sure everything looks right.

Then, it’s time to write your commit message. You can fill this in at the bottom of the page. A commit message is just a short summary of your changes. This consists of two parts: the subject and body.
‍

To create the clearest possible commit messages, we recommend following the “why, what, and how” approach, like so:

• What is the change? Summarize the change in one succinct sentence. For instance, "We're splitting the Americas up into NA and LATAM."
  
• Why did you decide to make the change? Explain the business context that led to your change. For example, “Due to a recent re-org in the sales team, we’ve decided to change how sales regions are defined.”
• How did you make the change? Describe the technical implementation and specific configuration changes. For instance, “We created new regions in Salesforce and assigned x people from the former Americas sales team to these new regions.”

Here’s how we recommend structuring your commit:

1. Subject - Cover the “what” and “why” of the change in a single line that'll capture the main gist, making it a breeze to review a list of changes quickly.
2. Body - Elaborate more on the “how” of the change, allowing whoever reads the commit message in the future to drill down as needed. This should include specific configuration changes, files affected, etc.

5. Open a pull request

So you now have two versions of your repo—one in main, and in the secondary branch you created. How do you update your main branch with these changes? And shouldn’t you run them by your team for review first? This is where pull requests come in and also where we get into the exciting, collaborative part of GitHub. A pull request is a proposed change (or changes) to a repo that a user submits for their collaborators to review and accept/reject. Up to this point in your journey, you’ve been on your own. Here’s where you can bring in your team.
‍

To open a new pull request, click the “Pull requests” tab of your repository and select “New pull request.”

Then, select the branch you created and “main” as the two branches you want to compare. Have a brief look over your request to make sure it’s what you want to submit, then click “Create pull request.” Give your pull request a title and a brief description. At this point, you can also add Reviewers, Assignees, Labels, Projects, or Milestones, by clicking the options to the right of your title and description. (You don’t necessarily need to add these yet, but they do provide useful ways of collaborating with your team.) Click create pull request.

If you’ve added them, your collaborators will now be able to review your changes and make suggestions.

6. Merge your pull request back into the main branch

Your team has reviewed your changes, you’ve had a little back and forth, and everyone seems happy with the final version. (If you haven’t added collaborators yet, that’s okay—you can also review and approve your own pull requests.) Now it’s time to merge your changes back into the main branch.

To do this, click “Merge pull request.” You likely shouldn’t have any conflicts at this point, but in the future, GitHub may alert you if there are any conflicts with material already on main. If this happens, GitHub will prevent you from merging your changes until the conflicts are resolved.
‍

Click “Confirm merge.” Once a message pops up saying the merge was successful, you can click “Delete branch” (you don’t need it anymore). The next time you want to make changes, you can open up a new branch and start the process over again.

That’s it! You’ve just explored the key functionalities of Git, from creating a branch, to committing a change, opening a pull request, and merging your changes. (That wasn’t so hard, was it?)