Guide: Getting Started with Github and Forks
This is a guide for people new to the world of git and Github. It tries to be pretty thorough, but feedback for improvement is always welcome.
Disclaimer: Many of the links in here are to guides that we didn't make. We can't do it all, people. At least, not all at once.
Tip: Don't worry, if you break something we can fix it. We have that power.
- You know what your command line interface is
- You have a Github account
Tip: If you have questions, ask them in the #cliff-effects-tech Slack channel.
-
Get our code.
- Make your own github copy of our repo (a fork).
- Download a copy to your own computer (locally). It'll be linked to your fork in a way that I'll explain later.
- Deal with changes to code.
- A bare-bones guide to git collaboration branch workflow
- Diagram of basic code-changing workflow
- Intro to branches
- New branches
- How all the repos relate to one another after you've set up.
To simplify, Github is a folder on a computer somewhere. The codeforboston account is a folder in the Github folder and the cliff-effects repo is a folder inside of that one - github/codeforboston/cliff-effects. Your account is also a folder in the github folder. Your browser is a way for you to see the stuff in those folders. It just looks prettier than your desktop folders.
Basically, we're going to copy the cliff-effects folder to different places so that we can make changes to files without messing up each others' work. It's a bit convoluted (for reasons), and there's a bit more to it - like how we link up those folders so we can sync them with each other - but we'll try to walk through that.
There will be a picture of these folders lower down when you've got some more details.
The workflow for this setup is completely different from the workflow you'll use in the future to work with the project. Right now it will go something like this:
codeforboston/cliff-effects -> youraccount/cliff-effects
|
v
Desktop/cliff-effects
Unless you delete your fork (which does happen sometimes to get a fresh start), you won't have to do this again.
First we're going to copy the github.com/codeforboston/cliff-effects folder into your Github folder - your account. Let's call that account 'youraccount' from now on. That's the folder online where you'll send your changes so that we can see them before bringing them into the official project's code.
Near the top-right of our repo page, there's a button that says 'Fork'. Click that. Now you'll have a new folder/repository in your github account that's also called 'cliff-effects' - github.com/youraccount/cliff-effects.
People will often call this your 'upstream' repository. Technically, 'upstream' is a more general term for any repository on the cloud, but that's the way things panned out. ¯\_(ツ)_/¯
Unless you delete your fork to start fresh, you won't have to do this again.
Note: This guide discusses how to use git, not the Github desktop app.
So the bummer about downloading your files to your computer is that the other contributors won't be able to see the changes you're making there. That's why we need your Github repository. On the other hand, working with them on your computer will be a lot easier than working with them on Github.
- Test if you have git by typing
git --versioninto your command line. If you don't get a number, you don't have git, so set up git. Make sure to follow all the instructions, including setting up authentication. - If you don't already have it open, open up your own account's cliff-effects repository. Make sure it's not the Code for Boston repository.
- Go to your profile (click on your user icon in the very top-right to see the menu item for it)
- Click on 'Repositories'
- Click on the one called 'cliff-effects'.
- You'll be able to tell it's your fork because it will have your username next to the words 'cliff-effects' at the top and it'll say it's a fork of 'codeforboston/cliff-effects'
- Near the top-right of your repository page should be a green button - 'Clone or download'. Click that. You have the option to use SSH or HTTPS. Use the one that you chose when you used git to authenticated with Github. This is what it looks like to clone with HTTPS on knod's repo:
- Once you've chosen SSH or HTTPS, click the 'copy' button. That'll automatically copy the right url for you to paste.
- Open Terminal and navigate to the folder in which you want to keep this project's folder. (Navigating in Windows and Mac.) What we're about to do will make a folder there called 'cliff-effects'. The rest of this guide is going to assume you put it in your Desktop folder.
- Type exactly
git clone, add a space at the end, and then paste the url that you copied from your Github repo. Hit 'enter'. You should get a message like this:
Cloning into `cliff-effects`...
remote: Counting objects: 10, done.
remote: Compressing objects: 100% (8/8), done.
remove: Total 10 (delta 1), reused 10 (delta 1)
Unpacking objects: 100% (10/10), done.
- Navigate into that cliff-effects project folder by typing
cd cliff-effectsand hitting 'enter'.
At this point you can follow the setup instructions to be able to see the project in the browser.
If you do delete your fork, we strongly suggest deleting this folder. If you can't stand deleting it, rename it, move it, or in some way keep it from getting confused with the new folder you create.
The full picture of our code to yours
So we've talked about how everything's folders, and now there's yet another layer of folders. These are what git calls your 'branches'. Every repo contains these 'branches'. You can see what folders/branches the codeforboston/cliff-effects repo has in it by going to that repo's page and clicking on the drop-down menu above the folders view with the words 'Branch: dev' on it. We should have, at the very least, 'dev', 'gh-pages', and 'master'.
When you forked our repo, you copied those branches/folders too. You can see them in the same way in any repo you have. In your local copy (your local repo), you won't be able to see these folders in your Finder or File Explorer, though. Even though they really are folders, the interface for git doesn't show them in that kind of linear way.
You're going to be jumping around in different branch-type folders a lot so that your changes don't get tangled with other people's changes, though, so it'd be good to be able to easily see which branch you're currently in. When your command line is navigated into the Desktop/cliff-effects folder, you can type git branch to see which branch/folder you're in. Right now you'll only have the branch 'dev'. You can tell what branch you're in because it'll be colored green and have a star to the left of its name.
Tip: Never edit or change files or folders while you're in the 'dev' branch.
(A more bare-bones guide to the workflow, in case you're already set up and already know the basics)
The workflow from now on is different. A very simple representation:
cfb/cliff-effects <----- youraccount/cliff-effects
| ^
| |
--> Desktop/cliff-effects --
The only branches/folders anywhere you need to worry about for this step are called 'dev'.
So there's yet another kind of folder. It's in your local repository. This is like a Dropbox folder, except it doesn't sync automatically. All it is is a folder that is linked to a specific repo in the cloud and contains whatever you've most recently downloaded from there. You can use this link to upload and download.
Right now, you have one of these branches already. Do git remote and you'll see a list of all the linked up names you have. Right now you should just see origin. That is name that git automatically gave to the link to your Github repo - your fork - when you did git clone. If you want to see the url it points to, do git remote -v. We'll work with that later. You now have to set up a link to the CfB repo.
Well, whenever your changes, or other people's changes, get accepted into the codeforboston/cliff-effects repo the contents of our 'dev' folder will probably be changed. If you don't manually sync up with us, you won't see our changes and, worse, when you make further changes and then try to send them to us, they may end up conflicting with the changes we've already made. That's why it's important to keep up to date with us.
So that you can pull in our changes, you need to set up what I call a 'linked folder'. I think I'm the only one that calls it that, though. It's like origin, but it'll be pointed at the github.com/codeforboston/cliff-effects folder. You can name it whatever you want, but I'm going to name it 'upstream' and that's how I'll talk about it from now on.
Unless you delete your fork to start fresh, you won't have to do this again.
- Go to the github/codeforboston/cliff-effects repo.
- Near the top-right of that page should be a green button - 'Clone or download'. Click that. You have the option to use SSH or HTTPS. Use the one that you chose when you used git to authenticated with Github. This is what it looks like to clone with HTTPS on knod's repo:
- Once you've chosen SSH or HTTPS, click the 'copy' button. That'll automatically copy the right url for you to paste.
- In the project's command prompt, type exactly
git remote add upstream, add a space at the end, then paste the url you just copied. - Tap 'enter'
- Do
git remote. You should see:
origin
upstream
You will need to do this every time you want to work on a new set of changes.
Tip: Always do `git checkout dev` before this next part to make sure you're on the 'dev' branch (in our terms - in the 'dev' folder).
- Now whenever you want to get changes from the codeforboston/cliff-effects/dev branch, do:
-
git fetch upstream dev. That downloads the changes into a folder called 'dev' in your 'upstream' 'linked folder'. -
git merge upstream/dev. Whatever branch you're in, git will try to combine the changes in the 'upstream/dev' folder with the ones you've made in the branch. If you haven't made any changes in the branch, there isn't any chance of any problems. If you do have problems, feel free to post about it in the #cliff-effects-tech Slack channel or to talk to one of us.
-
Tip: You can combine those commands into one command by just doing `git pull upstream dev`.
We suggest only ever doing this while in your own 'dev' branch because whatever changes you've made in a different branch may conflict with our changes and then it'll be a bit of a mess for you to work out.
- If you've got a good, clean, 'dev' branch that now exactly matches the CfB repo 'dev' branch, do
git push origin devto upload those changes to your online repository, your fork. This keeps your online repository in sync with everything else. We'll explain 'pushing' later.
I'm going to remind you to think of branches as folders. When you make a new 'branch', what you're basically doing is making a copy of the current folder/branch you're in (for example, 'dev') and giving it a name. Each branch should be for a group of changes that are all related to each other. The name should be something to give people a useful hint about what that branch is for. If you're changing the color scheme of the site, you might call it 'colors'. We'll tell you the commands to do that lower down.
If you make some changes on the 'colors' branch and you then do git checkout -b graphs to make a branch to work on graphs for a while, your color changes will get mixed in with your graph changes and we'll have a hard time accepting all those changes at once. What if we like the graph changes, but don't like the color changes? It'll be a mess to untangle. Try to not do that, but it happens to everyone sometimes. We'll help you work it out.
If you do want to work on graph changes, do git checkout dev and then do git checkout -b graphs.
Keep the changes in a branch focused on one topic at a time.
You will need to do this every time you want to make changes.
Tip: 'Save' early and often. It helps make sure that if you break your code, you can go back to working code.
We're going to pretend that you're going to call your new branch 'good-branch-name'.
- To make sure you're on the 'dev' branch, do
git checkout dev - Make a new branch with
git checkout -b good-branch-name - Edit files and save them the regular way.
Tip: To see what files you've changed, do `git status`. This will let you see the right filepath to use later, too.
Tip: To see all the specific changes you've made, do `git diff`.
-
git add: When you've got a group of edits that go together (for example, you've updated one color), dogit add file/path/file-name.whateverfor each file that you want to add. See the tips above for getting the correct file names. -
git commit: This truly saves your changes. If you mess up in the future, you can go back to any past commit that wasn't messed up. It's like the ultimate 'undo' button.- When you've added all the files that matter to this change, do
git commit. This will open an interface for adding a message. Each commit will need a commit message to let people know (or to remind yourself) what this change was about. - Tap 'a'.
- Write a short and useful description of what you've done. The convention is to write it in the present tense. For example 'Changes green to red.' Keep it shorter than 80 characters. If you need a longer description, there's a way to do it, but we won't go into it now. You'll get a different chance to leave us a longer explanation when you send us the request to accept your changes.
- When you're done, hit 'esc', then type in
:wqand hit 'enter'.
- When you've added all the files that matter to this change, do
- Do
git statusagain to make sure that you got all the files you needed. None of those files should show up anymore.
You will need to do this every time you want upload changes.
Uploading is called 'pushing' in git. Why would they call it something so strange? I think git was around before 'uploading' was the word everyone used, and everyone had their own name for it. Git called it 'pushing'.
- If this is the first time you're pushing this branch and its changes to your fork, do
git push -u origin good-branch-name. This pushes your changes, but-uhooks up this branch to remotely track the branch/folder on your online repository. It's useful for reasons, one of which is item #2 here. - If this isn't the first time, just do
git push.
This here is purely a Github thing. It's called a PR, or 'pull request'. You're requesting that we pull your changes into our 'dev' branch. That is, you're politely, through Github, asking us to go to our 'dev' branch and do git pull your-repo good-branch-name.
- Go to your fork on your account on Github.
- Use the drop-down menu that says 'Branch: dev' to pick the 'good-branch-name' branch.
- When that page finishes loading, there will be a button next to the drop-down menu called 'New pull request'. Click that button.
- You'll see a new page that looks like it has a comment at the top. In that comment will be one of two things.
- If you made just one commit, it'll be your commit message.
- If you made more than one commit, it'll be your branch name.
- If you need to, change the title of that comment to be more descriptive. Still keep it short.
- If you want to tell us even more, write more info in the body of the comment.
- Look over the code changes that are shown below to make sure they're what you wanted them to be. If they're not:
- Go back to your editor and make the changes you need to make.
-
git add file/path/file-name.whateverandgit commitagain. -
git pushagain.
- If you've also accepted an invitation from us to be a contributor, you can do a few other things if you want:
- Go to the right-hand column next to the 'comment'.
- Under 'Reviewers', select one or two reviewers. 'knod' is a good bet. Others might be 'ethanbb', 'wacii', or 'shp54'.
- Under 'Labels', if you see one or more labels that seems to match what you're doing, select it/them.
- Under 'Projects', do the same.
- When you're ready, at the bottom of the comment, click 'Create pull request'.
We'll try to get to that PR when we get a chance. If you get impatient, you can try posting in the #cliff-effects-tech channel to see what's up.
/cfb /youraccount
/cliff-effects /cliff-effects
/dev <----- your changes ------ /bug-fix
| ^
| |
our changes ^
v your changes
| /Desktop/cliff-effects |
|----> /dev |
|----> /bug-fix ------------------
For a basic guide on how to keep your branches untangled as you make changes, check out our git workflow wiki page.
For those moments when you've broken something, checkout http://ohshitgit.com/
git status - Shows you what files have changes that haven't been committed yet. There are two types of these.
- Files that have changes that you've already added to the list of files that will be committed.
- Files that have changes, but that you aren't ready to be committed.
git branch - Shows you a list of the 'branch' names in your local repository (the one on your computer). The one with the star next to it is the one that your edits will change.
git diff - Shows you all the specific changes you've made to the code.
git remote - A list of names. Each of these gives you a link to an online repository that you can use to download or upload changes. The one to your own fork is automatically called 'origin'.
git remote -v - A list of the names of online repositories to which you have links plus the urls that they use.
git checkout -b branch-name - Make a new branch and go to it so you can start making new changes. branch-name can be whatever you want it be, but try to make it something that will give us a clue about what it's for.
git checkout branch-name - Move to a branch that already exists to work on changes there.
git add file/path/file-name.extension - Pick a file and set it up to be saved. That's called 'staging' a file.
git add . - Add all files that have changes all at once. Yeah, we didn't tell you about this earlier. It's easier to make mistakes with this one.
git commit - DO THIS A LOT. Really, truly, for real save these changes so that if you mess up in the future you (or we) can go back to a version that's not messed up anymore. It also helps us fix things when we notice that something got broken a while ago. We can track it down much more easily.
git pull name-you-already-made some-branch-name - You've set up a folder with some name. When you set it up, you linked it to some repository at some url. Download changes from a branch in that repository and merge them into the branch that you're at. name-you-already-made can be any name you've created with git remote add. some-branch-name has to be the name of a branch that's in that online repository. This command really combines git fetch and git merge.
git fetch name-you-already-made some-branch-name - You've set up a folder with some name. When you set it up, you linked it to some repository at some url. Download changes from a branch in that repository and save them on your machine in a branch in that folder - 'name-you-already-made/some-branch-name'. name-you-already-made can be any name you've created with git remote add. some-branch-name has to be the name of a branch that's in that online repository.
git merge name-you-already-made/some-branch-name - Combine the code in that folder with the code in the branch you're at. name-you-already-made can be any name you've created with git remote add. some-branch-name has to be the name of a branch that's in that online repository.