Revision as of 15:29, 25 February 2020

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 & Git through the command line. It's a recommendation as there exist much more documentation & guides on how do things in Git through the CL than using GitHub Desktop or any other graphical interface.

Reading this guide

• In most places/steps, it's first written in bold the action to be done, and afterwards an explanation of what it does, and why it's done. This is to make revisiting the guide quicker when you already remember what each step means, but don't remember the exact commands/actions or their order.
• Start with reading the guide's [Short Git Guide#Glossary Glossary] to understand commonly used words or phrases in the guide. If you encounter words you don't understand, google for it together with "git" or "github", as it is likely a term linked to them. The author of the guide has English as a second language.
• If you are unsure what a word or phrase means here, look at the guide's Glossary, or
• 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, such as Roll20's API Script repo.
• 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.
8. 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.

Workflow

When you work with git/github, you keep your "master" branch up to date with Roll20's master branch, and when you work on making changes to something, you create a new branch from your up-to-date master branch and commit changes there. This way your master branch is still intact if you want to create a more branches to work on other things/sheets, without having the work-in-progress in your other working branches interfere with this new branch. This will also mean that if you mess up something in your working branch, your master branch and other working branches are intact.

Commonly used commands

The central commands you will need for everyday work with your local copy, your GitHub repo & Roll20's repo.

• git fetch - will fetch links on any changes and new branches done in your GitHub repo. If you specify a name of a remote after it, it will fetch update links from that remote. (E.g. git fetch upstream will do this for Roll20's repo, as we had set the "upstream" name to track Roll20's repo)
• git pull - will pull any changes done in your GitHub repo from the branch with the same name(if the active branch has tracking).
• git branch - lists all your local branches. if you type git branch name-of-branch it will create a new branch with the name
• git checkout name-of-branch - switches which branch you have active, to the branch-name you have selected. If you write -b before the name, you create the branch before changing to it, making it redundant to first type git branch name-of-branch
• git add . - will index all changes you have made. The "." specifies to index all changes in the repo. This index will later be used by git commit to save the changes.
• git commit -m "ExampleRPG: write-description-here" - saves all changed registered by git add ., and saves what's written inside the double quotes as a description for your saved commit.
• git push - will push any new commits made in the branch you're working in, to a branch on your GitHub with the same name, if you have set up an upstream for it. If you don

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 on GitHub, and save the changes to your master branch on 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.) If you want to update some of your working branches, in Step 1 you need to do git checkout name-of-the-branch instead.

Only the commands:'

• git checkout master
• git pull upstream master
• git push

Updating a work-in-progress branch

If you have some branch you have been working on for a longer time, and want to update to not lag behind the master branch too much, you can update your branch as well. Note: This has the potential to create merge conflict if changes to the same files you have been working on have been saved to Roll20's repo. Do this only if you're sure, or create a copy of your working branch as a backup in case the update goes wrong.

1. type git checkout name-of-your-branch - This switches your active branch to the one you want to update
2. Type git pull upstream master- This will fetch & merge any updates Roll20's main repo have done on GitHub, and save the changes to your active branch . If the CL doesn't give any complaints.
3. Type git push. This will update your copy of the branch on Github to be up to date with your local copy. Now if you look at the branch on Github, it will say it is 0 commits behind, and X commits ahead, meaning the only difference between the branch and Roll20's master branch is the changes you have worked on, and isn't lagging behind. This will make comparison of changes & creating PRs easier.

Creating a small fix to a character sheet & saving it on your Github repo

Situation: You have been made aware of a tiny bug for the ExampleRPG's character sheet, and know what to edit in the sheet's .html-file; someone have misspelled an attribute in the button for Strength-checks. But you don't know your way around Git/GitHub too well. This is how to do it.

1. Open a CL in your local repo's folder. Type git checkout master to set your master branch as the active one.
2. You will now create a new branch. Type git branch ExampleRPG-smallfix.
3. Type git checkout ExampleRPG-smallfix and now it will be the active branch where you can start working.
4. Find and Open the .html-file for ExampleRPG, and edit it with any text editor you want, and then save the changes.
5. In your CL, type git add .. (This will update Git's tracking to note all the changes you made in your repo this far for later use. Now we have only changed one file.)
6. Type git commit -m "ExampleRPG: Str-button fix". (This will commit all tracked changes with a message describing what you did. As there are many character sheets and people collaborating with the character sheets, it's a good idea to first mention the affected character sheet, and then a short description of what changed. This will later help you & others to read old commits and change history when searching bugs or similar)
7. Type git push -u origin ExampleRPG-smallfix. (This will telling git it's a new branch that should be tracked to your Github, while push your changes to your GitHub. If you go and see your GitHub repo in the browser, you should see that a new branch have been created)

Submit a Pull Request to Roll20(Github)

This is a continuation of the previous example, where you Create a PR based on a branch you have on your GitHub.

1. Open a browser to Roll20 Github Repo, and and if you recently updated one of your branches, there should be a yellow notification at the top mentioning this, and a button to to create a Pull Request. Press this button. (If this doesn't appear, navigate to your own Github repo's page, where you find a button saying "Create Pull Request". Before you press it, you can from the dropdown beside it select the name of the branch you want to make a PR from, and it will be automatically set the tcorrect one. If you don't, you need to change the dropdown when you are on the page in the next step)
2. Change the title of the Pull Request to clearly indicate what it is about. We'll change the name to "[ExampleRPG] Str button fix". In the Description section, we write "This fixes an attribute name typo in the Str button., and leave no other comment as this was a small change.(Now our PR will have the same naming format as PRs submitted by other people, and have a short description of what what it does. This will make it easier for others to get a quick & self-explanatory overview of what the PR is about. In this example the description & title-change of the PR might seem a bit redundant, but will be much more useful when you make lot of changes, or of the PR consists of several commits)
3. Now the Pull Request is submitted, and you see the description looks like. At the end of the description, there is a list of checkboxes that needs to be checked, so that Roll20 have easier to know what the PR is about. We check the two first boxes, as we mention the character sheet's name in the title, and this is a bug fix.

Now the pull request is submitted, and will eventually be reviewed by Roll20(Review happen once a week, on Mondays). They may comment on it and request some clarifications or changes, but in this case they will likely approve and merge it without problems. When the pull request turns from green to purple, Roll20 have merged the changes into the main repo.

Working with multiple branches

If you work on updates to two different sheets, the smart thing to do is to have separate branches for each update.

Let's say you have recently been working on creating a ship page for the MegaSmashRPG character sheet, but also want to start working on a visual update to ExampleRPG. You don't quite remember if you commited all your changes for MegaSmashRPG, and don't remember what branch you have active.

1. type git branch. It shows the list of branches you have on your local repo, and shows an asterisk next to the branch that's active, and in this case it shows "MegaSmashShipupdate".
2. type git add .. This indexes all your un-tracked changes if you this command wasn't the last thing you did last time. If the CL say enything, you can skip step 3 and 4.
3. type git commit -m "MegaSmashRPG: Ship update". This will save all this last change you did, and give the commit a name that tells what the cahnges was related to, even if you don't rememeber the details. This is still better that a commit message that says "last changes", as it won't later tell anyone any context on what it contains.
4. (Optional) type git push. If you had previously already saved this branch on Github with git push -u origin MegaSmashShipupdate, this will update your github with the changes from your computer. Now others can see how long you current progress since you updated your github the last time. This will also save your progress on the internet for you in case a mimic destroys and eats your computer.
5. type git checkout master. You have now changed your active branch to master which is the "clean" branch we want to start form if we want to work on something new.
6. type git checkout -b ExampleRPG-visual. This will create a fresh new branch based on your master branch, with a name that makes sense to you and what you intended to work on. if you don't first switch to the master branch before performing this step, you would also copy all your work on MegaSmashRPG to this branch, which will cause you trouble when you try submit your next PR.
7. Open up the files for ExampleRPG and work on the changes you want. Remember to save often, in case a goblin comes and turns of your computer while you're working. (Let's say you worked on improving how the inventory section looked like, and adjusted some colors.)
8. type git add . This indexes all your un-tracked changes you have done since you last used the command.
9. type git commit -m "ExampleRPG: Visual update on inventory, small color adjustments". Now we have commit all our changes, togeteher with a commit message that describes what we did.
10. (Optional) type git push -u origin ExampleRPG-visual. This will update your github to have the new branch you just created, tell this branch on your computer to push/pull/fetch things from there in the future, and upload all your changes. When you later work in this branch, you can type just git push and it now knows where to send things.
11. (Optional) git checkout master. Now your have set your active branch to "master", which means next time when you decide to work/check on things, you know you shouldn't have any uncommitted changes laying around. It will make for an easier starting point next time around.

How to Collaborate

If you want to collaborate with someone to create a single PR for both of your works, you can set up remote tracking to your collaborators GitHub so you can pull their latest work to your computer without having to wait for them to be merged to Roll20's repo first.

1. Find/get a link to your collaborator's Github repo. (check Step 6, First Time Setup). If they don't have a fork of the Roll20 repo, they must first create one. (For example, if your collaborator is Anduh, the url would be:https://github.com/Anduh/roll20-character-sheets.git)
2. Open up the CL in your working folder, and type git remote add name-you-want-for-this-remote https://github.com/name-of-your-collborator/name-of-their-repo.git. (For example, if your collaborator is "Anduh", it would be smart to name the remote simply that. the command would then look like git add remote Anduh https://github.com/Anduh/roll20-character-sheets.git)

Create a copy of someone's branch

(This is an continuations directly from the previous section.) Let's assume Anduh have been working on an update to ExampleRPG, you know his branch is up to date with roll20. You want to save it for yourself on your local copy.

1. type git checkout master to set active branch to your master branch.
2. type git fetch Anduh. This will update refs from the remote, and informing if about changes since last time you checked, as well as new branches. This info is displayed in the CL, and among things it shows that Anduh has a branch named "ExampleRPG-v1_5", which sounds right.
3. type git checkout -b ExampleRPG-Anduh-v1_5. This will create & switch us to this new branch, which we named in a way that reminds us that this isn't something we are working on.
4. type git pull Anduh ExampleRPG-v1_5. This will pull all the changes from the "ExampleRPG-v1_5" branch in Anduh's remote and save it in this branch. Now, while you have the "ExampleRPG-Anduh-v1_5"-branch active, can go and see his changes to the sheet, without having it interfere with any work you have saved up.

(Optional) Save the branch on github

1. type git pull -u origin ExampleRPG-Anduh-v1_5. This will create this branch in your GitHub repo, and save all it's info there as well.

Glossary

• "CL": shor for "command line" or "command line prompt" in this guide
• "your local copy/your working folder": 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.
• "PR": Pull Request, a GitHub concept.
• "ref/refs": reference, references. git-specific meaning
• "origin": Is the original source your local copy was cloned from. In this guide, it refers to your GitHub fork/repo. When you perform most git commands that sends or receives info, it will assume you refer to this "origin" remote, rather than someone other remote you hav defined, such as "upstream"
• "upstream": In this guide, it refers specifically to Roll20's remote repo, which we have defined as being named "upstream". For more, see Git Forks & Upstreams

See Also

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