A Modder's Guide to Git: A Primer on Version Control

Many mods for Baldur's Gate 3 are being uploaded on GitHub, and it's easy to see why that's the case: If you've looked through this repo, you can see everything that goes into the Community Library, without even needing to download it. Having a wiki attached means documentation is a step away, and reporting problems or requesting features is easy with the Issues tab. But how do you set it all up like this? What kind of technical know-how do you need? Why are other modders telling me to make a Pull Request, and how do I do that? These questions, and more, are what this guide aims to help you with.

Table of Contents

• Getting Started
• The Difference between Git and GitHub
  • Git
  • GitHub
• Working With Repositories
  • Repositories
  • Initializing a Repository
  • Cloning a Repository
  • Getting Familiar with GitHub (Optional)
• Branch Management
  • Branches
  • Checking Out/Creating a Branch
  • Adding and Committing Changes
• Remote Branch Management
  • Forking
  • SSH Keys
  • Fetching and Pulling Changes
  • Pushing Changes

What is Version Control?

First, let's dive into the key concept that Github, and more specifically, Git, is design to solve: Version Control. Version Control is a way of managing different versions of your code, allowing you to quickly roll back to older versions of your code when something goes wrong. It also allows you to work on multiple parts of your mod at once, without worrying about one set of features breaking things when you want to test something. In a nutshell, Version Control keeps track of every change you make, storing it in a way that allows you to go back and forth, without risking losing hours or even days of hard work if something goes wrong. There are a few different types of version control, but one of the most common ones you'll see these days, and the one used by several BG3 Modders, is Git.

Getting Started

Git is primarily handled via a Command Line Interface, though there are desktop and IDE GUIs for using it. This guide will walk you through using it from the Command Line - once you're comfortable with the concepts I explain here, feel free to explore these if you prefer. Install and/or prepare the tools below, and then we'll get into some of the ideas behind Git.

Tools

• Git: If you're modding on a Mac or Linux machine, chances are, you already have this. If you're on Windows, you'll need to install Git
• A Github Account: We'll be explaining Git through the lens of GitHub, one of the more commonly seen Git Repository sites, and the one used most often by BG3 Modders.
• A Text Editor: I recommend using VSCode for modding, however Notepad++ and even just plain Notepad work fine.

---