Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Short Git Guide"

From Roll20 Wiki

Jump to: navigation, search
m (See Also)
(add "Clean up Commits"-section)
(16 intermediate revisions by one user not shown)
Line 1: Line 1:
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.
+
This is a short guide on how to work with Git/GitHub locally on your computer, and how to update your fork of [https://github.com/Roll20/roll20-character-sheets Roll20's GitHub Repository], using the Git Command Line(CLI).
 +
{{NavSheetDoc}}
 +
The guide is aimed towards people who want to work with Roll20's Character Sheets and be able to interact with Roll20's Github & Git through the command line(CLI). It's recommended by those who do lots of work on character sheets and/or juggles more that one sheet at a time.
 +
 
 +
==Why Git CLI instead of GitHub Desktop?==
 +
* Git command line(CLI) have more guides & [https://git-scm.com/docs documentation] than the GitHub Desktop/Browser
 +
* Using the CLI makes it easier to troubleshooting, as you clearly know what steps you took, and can see the messages or error message the CLI gives back, which you can then search for on the web or share with others
 +
* Learning to use Git makes you have a better understanding of how Git/GitHub works. GitHub is essentially a website hosting Git, with a few extra features.
  
 
== Reading this guide ==
 
== 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.  
 
* 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.  
+
* 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.
* 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 should work universally, with the install & setup of Git on your computer working differently depending on your operating systems. In some places help for Windows-users are linked, while Linux-users are assumed to knowing or figure out the basics.  
* 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 ==
 
== First Time Setup ==
Line 14: Line 20:
 
# '''Download and install Git on your computer.''' [https://www.atlassian.com/git/tutorials/install-git Atlassian Guide For Linux/Mac/Windows]
 
# '''Download and install Git on your computer.''' [https://www.atlassian.com/git/tutorials/install-git Atlassian Guide For Linux/Mac/Windows]
 
# '''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.
 
# '''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.
# '''Open up a command line prompt(CL) in this folder.''' [https://www.thewindowsclub.com/how-to-open-command-prompt-from-right-click-menu Windows guide]
+
# '''Open up a command line prompt/interface(CLI) in this folder.''' [https://www.thewindowsclub.com/how-to-open-command-prompt-from-right-click-menu Windows guide]
 
# '''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 <code>https://github.com/YourGitHubUserName/roll20-character-sheets.git)</code>  
 
# '''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 <code>https://github.com/YourGitHubUserName/roll20-character-sheets.git)</code>  
 
# '''Type <code>git clone </code> and the url you have from Step 5.''' (for me this would look like: <code>git clone https://github.com/Anduh/roll20-character-sheets.git</code>). 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 <code>git push</code> or <code>git fetch</code>, it will act as if you had typed <code>git push origin</code> or <code>git fetch origin</code>, interacting with your GitHub fork. More on this later.
 
# '''Type <code>git clone </code> and the url you have from Step 5.''' (for me this would look like: <code>git clone https://github.com/Anduh/roll20-character-sheets.git</code>). 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 <code>git push</code> or <code>git fetch</code>, it will act as if you had typed <code>git push origin</code> or <code>git fetch origin</code>, interacting with your GitHub fork. More on this later.
# '''Navigate your command line prompt to be inside the folder created in Step 6.'''
+
# '''Navigate your CLI to be inside the folder created in Step 6.'''
 
# '''Type in <code>git remote add upstream https://github.com/Roll20/roll20-character-sheets.git </code>.''' 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.
 
# '''Type in <code>git remote add upstream https://github.com/Roll20/roll20-character-sheets.git </code>.''' 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 ==
+
== Commonly used commands ==
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.
 
The central commands you will need for everyday work with your local copy, your GitHub repo & Roll20's repo.
  
Line 32: Line 35:
 
* <code>'''git add .'''</code> - will index all changes you have made. The "." specifies to index all changes in the repo. This index will later be used by <code>git commit</code> to save the changes.
 
* <code>'''git add .'''</code> - will index all changes you have made. The "." specifies to index all changes in the repo. This index will later be used by <code>git commit</code> to save the changes.
 
* <code>'''git commit -m''' ''"ExampleRPG: write-description-here"''</code>''' - saves all changed registered by <code>git add .</code>, and saves what's written inside the double quotes as a description for your saved commit.
 
* <code>'''git commit -m''' ''"ExampleRPG: write-description-here"''</code>''' - saves all changed registered by <code>git add .</code>, and saves what's written inside the double quotes as a description for your saved commit.
* <code>'''git push'''</code> - 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
+
* <code>'''git push'''</code> - 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 haven't, the command line will tell you this, and display an example of the command to create an upstream tracking to your repo.
 +
 
 +
== 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.
  
 
=== Update Your Fork ===
 
=== 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'''.
+
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|First Time Setup]].
  
# '''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 <code>git checkout master</code> to switch to your master branch.
+
# '''Open a CLI, and navigate it to be inside your repo's folder.''' - If you're unsure whether you have your master branch active, type <code>git checkout master</code> to switch to your master branch.
 
# '''Type <code>git pull upstream master</code>''' - 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.
 
# '''Type <code>git pull upstream master</code>''' - 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.
# '''Type <code>git push</code>.''' - 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 <code>git checkout name-of-the-branch</code> instead.
+
# '''Type <code>git push</code>.''' - This will prompt the CLI 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 <code>git checkout name-of-the-branch</code> instead.
  
''Only the commands:'''
+
'''Only the commands:'''
 
* <code>git checkout master</code>
 
* <code>git checkout master</code>
 
* <code>git pull upstream master</code>
 
* <code>git pull upstream master</code>
Line 50: Line 56:
  
 
# '''type <code>git checkout name-of-your-branch</code>''' - This switches your active branch to the one you want to update
 
# '''type <code>git checkout name-of-your-branch</code>''' - This switches your active branch to the one you want to update
# '''Type <code>git pull upstream master</code>'''- 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.
+
# '''Type <code>git pull upstream master</code>'''- This will fetch & merge any updates Roll20's main repo have done on GitHub, and save the changes to your active branch . (If the CLI doesn't give any complaints.)
 
# '''Type <code>git push</code>.''' 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.
 
# '''Type <code>git push</code>.''' 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.
  
Line 57: Line 63:
 
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 <code>.html</code>-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.
 
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 <code>.html</code>-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.
  
# Open a CL in your local repo's folder. Type <code>git checkout master</code> to set your master branch as the active one.
+
# Open a CLI in your local repo's folder. Type <code>git checkout master</code> to set your master branch as the active one.
 
# You will now create a new branch. Type <code>git branch ExampleRPG-smallfix</code>.
 
# You will now create a new branch. Type <code>git branch ExampleRPG-smallfix</code>.
 
# Type <code>git checkout ExampleRPG-smallfix</code> and now it will be the active branch where you can start working.
 
# Type <code>git checkout ExampleRPG-smallfix</code> and now it will be the active branch where you can start working.
 
# Find and Open the <code>.html</code>-file for ExampleRPG, and edit it with any text editor you want, and then save the changes.
 
# Find and Open the <code>.html</code>-file for ExampleRPG, and edit it with any text editor you want, and then save the changes.
# In your CL, type <code>git add .</code>. ''(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.)''
+
# In your CLI, type <code>git add .</code>. ''(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.)''
 
# Type <code>git commit -m "ExampleRPG: Str-button fix"</code>. ''(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)''
 
# Type <code>git commit -m "ExampleRPG: Str-button fix"</code>. ''(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)''
 
# Type <code>git push -u origin ExampleRPG-smallfix</code>. ''(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)''
 
# Type <code>git push -u origin ExampleRPG-smallfix</code>. ''(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) ===  
+
=== Submit a Pull Request to Roll20(on Github) ===  
 
This is a continuation of the previous example, where you Create a PR based on a branch you have on your GitHub.
 
This is a continuation of the previous example, where you Create a PR based on a branch you have on your GitHub.
  
# 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)''
+
# 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 correct one. If you don't, you need to change the dropdown when you are on the page in the next step)''
 
# 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)''
 
# 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)''
 
# 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 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.   
Line 78: Line 84:
 
If you work on updates to two different sheets, the smart thing to do is to have separate branches for each update.
 
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.
+
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 committed all your changes for MegaSmashRPG, and don't remember what branch you have active.
  
# type <code>git branch</code>. 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".
+
# Open your CLI in the character sheet folder, and type <code>git branch</code>. 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".
# type <code>git add .</code>. 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.
+
# type <code>git add .</code>. This indexes all your un-tracked changes if you this command wasn't the last thing you did last time. If the CLI say anything, you can skip step 3 and 4.
# type <code>git commit -m "MegaSmashRPG: Ship update"</code>. 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.
+
# type <code>git commit -m "MegaSmashRPG: Ship update"</code>. This will save all this last change you did, and give the commit a name that tells what the changes was related to, even if you don't remember 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.
# (Optional) type <code>git push</code>. If you had previously already saved this branch on Github with <code>git push -u origin MegaSmashShipupdate</code>, 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.  
+
# (Optional) type <code>git push</code>. If you had previously already saved this branch on Github with <code>git push -u origin MegaSmashShipupdate</code>, 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.  
 
# type <code>git checkout master</code>. 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.
 
# type <code>git checkout master</code>. 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.
 
# type <code>git checkout -b ExampleRPG-visual</code>. 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.
 
# type <code>git checkout -b ExampleRPG-visual</code>. 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.
 
# 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.)
 
# 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.)
 
# type <code>git add .</code> This indexes all your un-tracked changes you have done since you last used the command.
 
# type <code>git add .</code> This indexes all your un-tracked changes you have done since you last used the command.
# type <code>git commit -m "ExampleRPG: Visual update on inventory, small color adjustments"</code>. Now we have commit all our changes, togeteher with a commit message that describes what we did.
+
# type <code>git commit -m "ExampleRPG: Visual update on inventory, small color adjustments"</code>. Now we have commit all our changes, together with a commit message that describes what we did.
 
# (Optional) type <code>git push -u origin ExampleRPG-visual</code>. 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 <code>git push</code> and it now knows where to send things.
 
# (Optional) type <code>git push -u origin ExampleRPG-visual</code>. 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 <code>git push</code> and it now knows where to send things.
 
# (Optional) <code>git checkout master</code>. 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.
 
# (Optional) <code>git checkout master</code>. 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.
Line 96: Line 102:
 
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.
 
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.
  
# 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 [https://github.com/Anduh Anduh], the url would be:<code>https://github.com/Anduh/roll20-character-sheets.git</code>)
+
# Find/get a link to your collaborator's Github repo. (check '''Step 6''', [[#First Time Setup|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 [https://github.com/Anduh Anduh], the url would be:<code>https://github.com/Anduh/roll20-character-sheets.git</code>)
# Open up the CL in your working folder, and type <code>git remote add ''name-you-want-for-this-remote'' ''https://github.com/name-of-your-collborator/name-of-their-repo.git''</code>. (For example, if your collaborator is "Anduh", it would be smart to name the remote simply that. the command would then look like <code>git add remote Anduh https://github.com/Anduh/roll20-character-sheets.git</code>)
+
# Open up the CLI in your working folder, and type <code>git remote add ''name-you-want-for-this-remote'' ''https://github.com/name-of-your-collborator/name-of-their-repo.git''</code>. (For example, if your collaborator is "Anduh", it would be smart to name the remote simply that. the command would then look like <code>git add remote Anduh https://github.com/Anduh/roll20-character-sheets.git</code>)
 +
 
 +
Now you have added the other person's repo as a remote, which makes it easier to copy any work they have going on by simply referring to the nickname you've give the remote, rather than having to use the full url of the repo.
  
 
==== Create a copy of someone's branch ====
 
==== Create a copy of someone's branch ====
Line 103: Line 111:
  
 
# type <code>git checkout master</code> to set active branch to your master branch.
 
# type <code>git checkout master</code> to set active branch to your master branch.
# type <code>git fetch Anduh</code>. 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.
+
# type <code>git fetch Anduh</code>. 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 CLI, and among things it shows that Anduh has a branch named "ExampleRPG-v1_5", which sounds right.
 
# type <code>git checkout -b ExampleRPG-Anduh-v1_5</code>. 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.
 
# type <code>git checkout -b ExampleRPG-Anduh-v1_5</code>. 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.
 
# type <code>git pull Anduh ExampleRPG-v1_5</code>. 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.
 
# type <code>git pull Anduh ExampleRPG-v1_5</code>. 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
+
'''(Optional)''' Save the branch on github
# type <code>git pull -u origin ExampleRPG-Anduh-v1_5</code>. This will create this branch in your GitHub repo, and save all it's info there as well.  
+
::5. type <code>git pull -u origin ExampleRPG-Anduh-v1_5</code>. This will create this branch in your GitHub repo, and save all it's info there as well.
  
 +
==== Creating a sheet update suggestion & sending it to your collaborator ====
 +
Continuing from the previous section where we created the <code>ExampleRPG-v1_5</code>-branch, taken from Anduh's Github repo, we now could start working on an suggested update on their sheet/update directly, instead of going through Roll20's official repo. This means two ore more people could collaborate on creating a larger sheet update among themselves by sending PRs back and forth, and then later would only one coherent PR be submitted to Roll20's repo, that contains work of the collaborators.
 +
 +
Let's assume (from the previous section) that the v.1.5 update for "ExampleRPG" that Anduh have been working on his <code>ExampleRPG-v1_5</code>-branch have miss-spelt a new attribute name that the update would introduce, and you want to create a quick fix that he could merge into his work.
 +
 +
# Open a CLI in your local repo's folder. Type <code>git checkout ExampleRPG-Anduh-v1_5</code>. This sets the active branch to branch containing the current version of Anduh's v.1.5 update that you have on your local repo.
 +
# type <code>git checkout -b ExampleRPG-Anduh-v1_5_attrfix</code>. This will create us a new working branch based on <code>ExampleRPG-Anduh-v1_5</code>, and changing it to be our active branch. If any mistakes are made here, we can always go back to and create a new branch from <code>ExampleRPG-Anduh-v1_5</code> without having to download it again.
 +
# Open the files for ExampleRPG, make the changes needed, and then save.
 +
# Type <code>git add .</code>. ''(Updates Git's tracking so all file changes will be committed with the next commit.)''
 +
# Type <code>git commit -m "ExampleRPG v.1.5: correct typo in attr name perception-mod "</code>. ''(Commits the changes & leaves a commit message clearly stating what was done)''
 +
# Type <code>git push -u origin ExampleRPG-Anduh-v1_5_attrfix</code>. ''(This will create  this branch on your github repo)''
 +
# On GitHub, navigate to your github repository, and then select and go to your <code>ExampleRPG-Anduh-v1_5_attrfix</code>-branch. Press on the "Create Pull Request"-button.
 +
# This will by default suggest to make a PR to "base repository: Roll20/roll20-character-sheets", "base:master" We will change this destination to instead be  "base repository: Anduh/roll20-character-sheets" and "base:ExampleRPG-Anduh-v1_5".
 +
# GitHub might take a few seconds to update, but it should now display the changes between the branches, which should only be one commit, the one we named ''"ExampleRPG v.1.5: correct typo in attr name perception-mod "''. If everything looks good, Update the PR title and description if needed and then press submit.
 +
 +
Now your fix to the ExampleRPG's v.1.5 have been sent to Anduh, and he can then on GitHub merge your changes, update his local branch, and when eventually submitting the update to Roll20, your commit will be included in it.
 +
 +
====Updating your branch when your collaborator have updated theirs====
 +
[[#Updating_a_work-in-progress_branch|Updating a work-in-progress branch]] is very similar to how we'd update our local copy/branch of of our collaborators work.
 +
 +
Continuing form the previous section, let's assume Anduh merged the attribute fix into his <code>ExampleRPG-Anduh-v1_5</code>-branch as well as some other changes, so now we want to update our copy of <code>ExampleRPG-Anduh-v1_5</code> so that we see the current state of the sheet, as well as be able to submit more updates without trouble.''(If you don't update your local version of the branch before making more changes and them submitting them, it will likely result in merge conflicts due to your files not being up-to-date)''
 +
 +
# Type <code>git checkout ExampleRPG-Anduh-v1_5</code>. ''(This switches your active branch to the one you want to update)''
 +
# Type <code>git pull Anduh ExampleRPG-Anduh-v1_5</code> - This will fetch & merge any updates from Anduh's repo for the branch named "ExampleRPG-Anduh-v1_5", and save the changes to your active branch. (If the CLI doesn't give any complaints.)
 +
# '''(optional)''' Type <code>git push</code>. This will update the branch on your GitHub as well.
 +
 +
 +
It's best to perform this step before each time you start working on a new change, to ensure you stay up-to-date with your files. You can now do [[#Creating_a_sheet_update_suggestion_.26_sending_it_to_your_collaborator_.3D|Creating a sheet update suggestion & sending it to your collaborator]] again without issue.
 +
 +
===Fixing your master branch===
 +
 +
Sometimes you might do something that result in you making changes to your master branch, which could cause troubles down the line. One way to revert these changes to your branch is by performing the <code>git reset</code> command and telling git to reset your branch to how Roll20's master branch currently looks like.
 +
 +
# When having the branch you want to reset be the active one, type <code>git reset --hard upstream/master</code>. This will force the currently active branch to reset so it is identical to the master branch of the "upstream"(the shorthand for Roll20's repository, as defined in [[#First Time Setup|First Time Setup]]). '''Warning:''' this will erase any changes you have done in this branch, so be sure to copy/save any WIP outside the repo.
 +
# (Optional) type <code>git push</code>. This will update the branch on your github repo, and making it easier to check if things are okay comparing to Roll20's repo on github. If there is some discrepancy between your local repo and your github repo after '''Step 1.''', you git might warn against pushing the changes to your github repo. If you're sure about performing this step, you can force the command to work by typing <code>git push '''--force'''</code>.
 +
 +
===Clean up Commits===
 +
If you end up having tons of commits, or want to rewrite the commit message for the latest one, you might want to consider ''squashing'' them.
 +
 +
'''Combining last two commits: Example'''
 +
 +
Let's say we are working on a small update to the ExampleRPG sheet, and we have saved our progress in two commits so far. But we realize now that we left very vague commit messages for both, <code>"fix inititive"</code> and <code>"ExampleRPG fix"</code>. We feel the update is good enough, but want to replace the vauge messages with one that clearly states which sheet was affected, the sheet version, and a short version of what was done.
 +
 +
# Type <code>git reset --soft HEAD~2</code>. ''This will remove the last two commits, but keep the changes from them, like if you only had saved the progress with <code>git add .</code> but not yet committed the changes.''
 +
# Type <code>git commit -m "ExampleRPG v.1.61: Fixed init bug & minor visual updates"</code>. ''This will become the new commit message for what we done, and it's now clear from the message alone what was done without having to check the actual changes.''
 +
 +
After this we continue as normal.
 +
 +
* You can find some other methods from: [https://gist.github.com/patik/b8a9dc5cd356f9f6f980#file-how-to-squash-commits-in-git-md Squashing Git Commits] by Patik
  
 
== Glossary ==
 
== Glossary ==
* '''"CL"''': shor for "command line" or "command line prompt" in this guide
+
* '''"CLI"''': shorr for "command line interface" or "command line prompt"
* '''"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 <code>git clone</code>.  
+
* '''"your local repo/copy/working folder"''': In this context I refer to the copy of your GitHub repo you have saved on your computer with <code>git clone</code>.  
 
* '''"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   
 
* '''"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.
 
* '''"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.
 
* '''"PR"''': Pull Request, a GitHub concept.
* '''"ref/refs"''': reference, references. git-specific meaning  
+
* '''"ref/refs"''': reference, references. [https://git-scm.com/book/en/v2/Git-Internals-Git-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"  
+
* '''"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 have 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 [https://www.atlassian.com/git/tutorials/git-forks-and-upstreams Git Forks & Upstreams]
 
* '''"upstream"''': In this guide, it refers specifically to Roll20's remote repo, which we have defined as being named "upstream". For more, see [https://www.atlassian.com/git/tutorials/git-forks-and-upstreams Git Forks & Upstreams]
  
== See Also ==
+
== Related Pages ==
* [https://wiki.roll20.net/Beginner%27s_Guide_to_GitHub Beginners Guide To GitHub] - made with Roll20 in mind
+
* [[Beginner%27s_Guide_to_GitHub| Beginners Guide To GitHub]] - Alternative guide to "Short Git Guide"
 
* [[Building Character Sheets]]
 
* [[Building Character Sheets]]
* [https://git-scm.com/doc Git Documentation] (git-scm.com)
+
* [[Andreas Guide to Sheet Development]]
 +
* [[Sheet Author Tips]]
 +
 
 +
==See Also ==
 +
* [https://www.atlassian.com/git/tutorials Atlassian Git Tutorials]
 +
* [https://git-scm.com/doc Official Git Documentation]
 +
* [https://cli.github.com/ GitHub CLI beta] - Take GitHub to the command line, and create PRs in the CLI instead of through the GitHub website or the Desktop application.
 
* [https://github.com/Roll20/roll20-character-sheets Roll20's Character Sheet Repository on GitHub]
 
* [https://github.com/Roll20/roll20-character-sheets Roll20's Character Sheet Repository on GitHub]
 +
* [https://wiki.roll20.net/Beginner%27s_Guide_to_GitHub#Git_and_Github_for_Poets_.28beyond_basics.29 Git/GitHub for Poets Youtube tutorial] - Teaches what they are, and the basics of how to use GitHub & Git basics
 +
* [https://rogerdudler.github.io/git-guide/ Git -The simple guide] by Roger Dudler
 +
 
<br>
 
<br>
 
<br>
 
<br>
 
[[Category:Guides]]
 
[[Category:Guides]]
 
[[Category:Character Sheet Creation]]
 
[[Category:Character Sheet Creation]]

Revision as of 17:25, 9 January 2021

This is a short guide on how to work with Git/GitHub locally on your computer, and how to update your fork of Roll20's GitHub Repository, using the Git Command Line(CLI).

The guide is aimed towards people who want to work with Roll20's Character Sheets and be able to interact with Roll20's Github & Git through the command line(CLI). It's recommended by those who do lots of work on character sheets and/or juggles more that one sheet at a time.

Contents

Why Git CLI instead of GitHub Desktop?

  • Git command line(CLI) have more guides & documentation than the GitHub Desktop/Browser
  • Using the CLI makes it easier to troubleshooting, as you clearly know what steps you took, and can see the messages or error message the CLI gives back, which you can then search for on the web or share with others
  • Learning to use Git makes you have a better understanding of how Git/GitHub works. GitHub is essentially a website hosting Git, with a few extra features.

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.
  • 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 should work universally, with the install & setup of Git on your computer working differently depending on your operating systems. In some places help for Windows-users are linked, while Linux-users are assumed to knowing or figure out the 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/interface(CLI) 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 CLI 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.

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 haven't, the command line will tell you this, and display an example of the command to create an upstream tracking to your repo.

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.

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 CLI, 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 CLI 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 CLI 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 CLI 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 CLI, 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(on 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 correct 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 committed all your changes for MegaSmashRPG, and don't remember what branch you have active.

  1. Open your CLI in the character sheet folder, and 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 CLI say anything, 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 changes was related to, even if you don't remember 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, together 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 CLI 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)

Now you have added the other person's repo as a remote, which makes it easier to copy any work they have going on by simply referring to the nickname you've give the remote, rather than having to use the full url of the repo.

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 CLI, 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

5. 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.

Creating a sheet update suggestion & sending it to your collaborator

Continuing from the previous section where we created the ExampleRPG-v1_5-branch, taken from Anduh's Github repo, we now could start working on an suggested update on their sheet/update directly, instead of going through Roll20's official repo. This means two ore more people could collaborate on creating a larger sheet update among themselves by sending PRs back and forth, and then later would only one coherent PR be submitted to Roll20's repo, that contains work of the collaborators.

Let's assume (from the previous section) that the v.1.5 update for "ExampleRPG" that Anduh have been working on his ExampleRPG-v1_5-branch have miss-spelt a new attribute name that the update would introduce, and you want to create a quick fix that he could merge into his work.

  1. Open a CLI in your local repo's folder. Type git checkout ExampleRPG-Anduh-v1_5. This sets the active branch to branch containing the current version of Anduh's v.1.5 update that you have on your local repo.
  2. type git checkout -b ExampleRPG-Anduh-v1_5_attrfix. This will create us a new working branch based on ExampleRPG-Anduh-v1_5, and changing it to be our active branch. If any mistakes are made here, we can always go back to and create a new branch from ExampleRPG-Anduh-v1_5 without having to download it again.
  3. Open the files for ExampleRPG, make the changes needed, and then save.
  4. Type git add .. (Updates Git's tracking so all file changes will be committed with the next commit.)
  5. Type git commit -m "ExampleRPG v.1.5: correct typo in attr name perception-mod ". (Commits the changes & leaves a commit message clearly stating what was done)
  6. Type git push -u origin ExampleRPG-Anduh-v1_5_attrfix. (This will create this branch on your github repo)
  7. On GitHub, navigate to your github repository, and then select and go to your ExampleRPG-Anduh-v1_5_attrfix-branch. Press on the "Create Pull Request"-button.
  8. This will by default suggest to make a PR to "base repository: Roll20/roll20-character-sheets", "base:master" We will change this destination to instead be "base repository: Anduh/roll20-character-sheets" and "base:ExampleRPG-Anduh-v1_5".
  9. GitHub might take a few seconds to update, but it should now display the changes between the branches, which should only be one commit, the one we named "ExampleRPG v.1.5: correct typo in attr name perception-mod ". If everything looks good, Update the PR title and description if needed and then press submit.

Now your fix to the ExampleRPG's v.1.5 have been sent to Anduh, and he can then on GitHub merge your changes, update his local branch, and when eventually submitting the update to Roll20, your commit will be included in it.

Updating your branch when your collaborator have updated theirs

Updating a work-in-progress branch is very similar to how we'd update our local copy/branch of of our collaborators work.

Continuing form the previous section, let's assume Anduh merged the attribute fix into his ExampleRPG-Anduh-v1_5-branch as well as some other changes, so now we want to update our copy of ExampleRPG-Anduh-v1_5 so that we see the current state of the sheet, as well as be able to submit more updates without trouble.(If you don't update your local version of the branch before making more changes and them submitting them, it will likely result in merge conflicts due to your files not being up-to-date)

  1. Type git checkout ExampleRPG-Anduh-v1_5. (This switches your active branch to the one you want to update)
  2. Type git pull Anduh ExampleRPG-Anduh-v1_5 - This will fetch & merge any updates from Anduh's repo for the branch named "ExampleRPG-Anduh-v1_5", and save the changes to your active branch. (If the CLI doesn't give any complaints.)
  3. (optional) Type git push. This will update the branch on your GitHub as well.


It's best to perform this step before each time you start working on a new change, to ensure you stay up-to-date with your files. You can now do Creating a sheet update suggestion & sending it to your collaborator again without issue.

Fixing your master branch

Sometimes you might do something that result in you making changes to your master branch, which could cause troubles down the line. One way to revert these changes to your branch is by performing the git reset command and telling git to reset your branch to how Roll20's master branch currently looks like.

  1. When having the branch you want to reset be the active one, type git reset --hard upstream/master. This will force the currently active branch to reset so it is identical to the master branch of the "upstream"(the shorthand for Roll20's repository, as defined in First Time Setup). Warning: this will erase any changes you have done in this branch, so be sure to copy/save any WIP outside the repo.
  2. (Optional) type git push. This will update the branch on your github repo, and making it easier to check if things are okay comparing to Roll20's repo on github. If there is some discrepancy between your local repo and your github repo after Step 1., you git might warn against pushing the changes to your github repo. If you're sure about performing this step, you can force the command to work by typing git push --force.

Clean up Commits

If you end up having tons of commits, or want to rewrite the commit message for the latest one, you might want to consider squashing them.

Combining last two commits: Example

Let's say we are working on a small update to the ExampleRPG sheet, and we have saved our progress in two commits so far. But we realize now that we left very vague commit messages for both, "fix inititive" and "ExampleRPG fix". We feel the update is good enough, but want to replace the vauge messages with one that clearly states which sheet was affected, the sheet version, and a short version of what was done.

  1. Type git reset --soft HEAD~2. This will remove the last two commits, but keep the changes from them, like if you only had saved the progress with git add . but not yet committed the changes.
  2. Type git commit -m "ExampleRPG v.1.61: Fixed init bug & minor visual updates". This will become the new commit message for what we done, and it's now clear from the message alone what was done without having to check the actual changes.

After this we continue as normal.

Glossary

  • "CLI": shorr for "command line interface" or "command line prompt"
  • "your local repo/copy/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 have 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

Related Pages

See Also