New Contributors Guide Git Overview

A brief introduction to git and github

CDDA's data and code files are stored in the cloud on github.com using a version control system called git.

A version control system is a program that keeps of a bunch of files and records changes to them. It can provide the text of the changes, send those changes to someone else, apply someone else's changes, or revert the files to a previous version.

A repository or repo is the entirety of a program's files and recorded changes. The CDDA primary repo is stored at https://github.com/CleverRaven/Cataclysm-DDA and is sometimes called the "CleverRaven repo" or the "upstream repo". You'll need your own copy of the CleverRaven repo stored on your user account at github.com. Creating your own copy of the repo is called "forking the repo" (as in a fork in the road). You can also clone a repo, which means copying it from one location to another. You can clone your fork of the CleverRaven repo to copy it out of the cloud and onto your desktop machine or laptop. If you do that, the clone of your fork on your machine is the "local repo" and the copy of your fork on github.com is the remote repo. You can also use github.com's tools to make changes directly on your remote repo. You can also have multiple remote repos, which is useful when you're working with other people and want to use git to look at their code or even add it to your local repo.

Each repo is a collection of files, branches, and commits. Each commit is a set of changes to some files that are all supposed to happen together. For instance, if you added a new item in JSON, there would be a change to the JSON file for the item's definition, a change to another JSON file for the recipe to craft the item, and a change in another JSON file to add the item to the lists of items that spawn in the game. All three changes would be grouped together in a single commit. Commits have some meta-data attached to them: a unique commit hash that looks like this: 19b0032cd20a2f2cc5ae19178562cf1c8af2a42e, the name of the person who wrote the commit, and a short message describing the purpose to the commit.

Each repo has one or more branches. A branch is a list of commits that are indicate the order in which changes are supposed to occur. The same commit can occur in multiple branches, possibly with a different commit hash. Each branch is independent of every other branch. You can add commits to one branch without changing any other branch.

By tradition, the master branch is the standard release branch for each repo. You should never add code directly to your master branch, but instead it should always be an exact copy of the master branch of the CleverRaven repo. Instead, you should create a new branch for each feature you want to add.

The branch you are currently working on contains the "working set" of your repo, which is just the changes you are currently working on. You can check out branches, which causes git to replace your current working set with the changes from the new branch. By committing changes and then changing branches, you can work on different projects at once without needing to clone the entire repo again.

When you are happy with all the commits you want to make for a branch in your local repo, you can "push" those changes to your remote repo, storing them on github.com. When your changes are in your remote repo, you can open a "pull request" or "PR" against the CleverRaven repo, which is a request to add those changes to the CleverRaven repo's master branch. One of the maintainers will review your PR and eventually "merge" it into the CleverRaven repo's master branch, at which point your changes will become part of CDDA.

There is a whole lot more to know about git: literally entire books worth of information. This is a quick overview to get you started. If you want to know more, just google some git tutorials.

git clients

The program you use to interact with a repo is called a git client. Browsing github.com through the web interface provides a minimal git client, but for serious work, that isn't recommend and you should download and install a better client on your local computer.

Command line git is available on Linux, and there is a git bash for Windows that provides similar functionality on Windows. Command line git can be intimidating for new users, but it's fast and powerful after you get minimally proficient in it.

github desktop or gitkraken are GUI driven git clients that have gotten good reviews. There are many others; a quick web search will find many of them. You may need to experiment a bit to find a git client that you find easy to understand and that works foryou.

Getting Started

You'll need to set up a github.com account and fork the CleverRaven repo before you start making any changes. Return to Getting Started for instructions on how to do that.