This is a short guide on how to work with Git/GitHub locally on your computer, and how to update your fork of someone else project. The guide is aimed towards people who want to work with Roll20's Character Sheets and be able to interact with Roll20 Github in a simple way through the command line.

Reading this guide

• In most places/steps, I first write in bold the action to be done, and afterwards an explanation of what it does, and why.
• If you are unsure what a word or phrase means here, look at the guide's Glossary, or google for it together with "git" or "github" to find related explanations.
• The GitHub repository for Character sheets are used as an example here, but it works the same with any other GitHub project you have forked.
• This guide is made with Linux in mind, but some thought have been made to make the guide as universal as possible, with the install of Git on your computer working differently on different operating systems. In some places help for Windows-users are linked, with assumption of Linux-users knowing basics.

First Time Setup

If you've already worked with a GitHub desktop or other graphical user interface, some steps are redundant, and should be skipped if it seems to create duplicates. The setup in Step 7. will be needed for the "Update your Fork"-section if you otherwise already have a github fork and a local copy.

1. Have your own GitHub account, and have a fork created from Roll20's repository. (When logged into GitHub, press the "fork" icon in the upper left corner of this page. It will ask you to name your fork, and my recommendation is to keep the default name, as it will keeps things simple later). Now you have your own fork of the repo, that you can do whatever you want with, but it's still only on the internet, and we want to make a local copy on your computer.
2. Download and install Git on your computer. Atlassian Guide For Linux/Mac/Windows
3. Go to your file manager, and navigate to a folder where you want to place your copy of the roll20 repo. The "Documents" folder is a good choice.
4. Open up a command line prompt(CL) in this folder. Windows guide
5. Copy the URL for your GitHub fork. Open up your browser and navigate to your Github Fork. On the left side is a green "Clone or Download" button, and if pressed, show an url that ends in ".git", which you will need in the next step. Copy it somewhere easily accessible for Step 6. (it should look something like https://github.com/YourGitHubUserName/roll20-character-sheets.git)
6. Type git clone and the url you have from Step 5. (for me this would look like: git clone https://github.com/Anduh/roll20-character-sheets.git). Now git is downloading and making you a local copy of your GitHub repository, and it may take some time. This will automatically set your GitHub fork as the default remote (called "origin"). When you later use commands like git push or git fetch, it will act as if you had typed git push origin or git fetch origin, interacting with your GitHub fork. More on this later.
7. Navigate your command line prompt to be inside the folder created in Step 6. (On) Type in git remote add upstream https://github.com/Roll20/roll20-character-sheets.git . This will set up Roll20's repository as an remote called "upstream" for your local copy, where you can pull updates from. This will be used later in the "update your Fork" section.

Update Your Fork

If you use GitHub Desktop or other method to work on your local copy, you can still use this section to streamline how you update your fork against Roll20's repo. This requires to have done Step 7. from First Time Setup.

1. Open a CL, and navigate it to be inside your repo's folder. If you're unsure whether you have your master branch active, type git checkout master to switch to your master branch.
2. Type git pull upstream master. This will fetch & merge any updates Roll20's main repo have done in GitHub, and save the changes to your local copy.
3. Type git push. This will prompt the CL to ask for your github username & password to approve the changes you are now trying send to your GitHub repo. When you have successfully provided your username & password, you have now managed to update both your local copy and your GitHub repo to be up to date with Roll20's main repository. (There are methods to automatically send the username and password to avoid needing to write it each time for both Windows and Linux.)

Workflow with Git

This is how you can use Git to work on your sheets, and to pull/push updates to your GitHub.

Examples

These examples assumes your local copy & Github fork.

Creating a quick fix to a character sheet & and sending it to Roll20

1. Open a CL in your local repo's folder. Type git checkout master to set your master branch as the active one.
2. Type git branch ' Create a new branch with a unique name

How to make Collaboration easier

todo

Glossary

• "CL": shor for "command line" or "command line prompt" in this guide
• "your local copy": In this context I refer to the copy of your GitHub repo you have saved on your computer with git clone.
• "your Github Repo/fork": Refers to the GitHub repo you have forked from Roll20 repo. It's the repo you "local copy" interacts and mirrors with when you do most things
• "repo": short for a Git/GitHub "repository". A Git repository is a virtual storage of your project. It allows you to save versions of your code, which you can access when needed.

See Also

• Beginners Guide To GitHub - made with Roll20 in mind
• Building Character Sheets
• Roll20's Character Sheet Repository on GitHub