Quick guide to Git + Github
Who’s this guide for ?
- You just joined an organization or project and are required to use github, you can’t figure it out, want a simple overview and/or are afraid to ask some basic questions.
- You forgot for the nth time how to setup a project on github or want to check someones setup ( you can skim/skip the next section )
Note: When I started working with git/github I dismissed them as simple tools I should be able to learn in a few minutes, they proved to be more complex and difficult to learn, you might fare better, but it's still helpful to have a humble mentality when starting out and take your time.
- Git and Github, Gitlab, Bitbucket, etc ?
Git is a popular version control system… in other words it’s a way for you to keep track of changes you make to a piece of software or code, Github, Gitlab, Bitbucket and other sites allow you to host online ( in the internet aka their servers ) said piece of code along with git’s functionality, and depending on your organization and pipeline, can integrate other cool features like collaboration and automated testing and deployment.
At it’s most basic and perhaps most fundamental, git allows you to not screw up things too much while developing software, gives you and others peace of mind by letting you go back to a place in time when your code was not screwed up, keeps track of changes you’ve made so you know when you screwed up and on and on ( notice the key word here is screwing up which one tends to do a lot when writing code ), when paired with a hosting service like github, gitlab, bitbucket or others; it let’s you and organizations work collaboratively, allows remote development and provides a place to store, organize and launch code, it can scale to hundreds of developers working on a project while still providing the screw up prevention tools ( screw up potential is now infinite ) .
It might seem that git and github are a requirement for software development, either personal or when doing it commercially, but in reality you can do most of what git and github do on your own with little overhead or technical debt, github is also not a fully fledged hosting site, you could for instance roll your own :
Poor Mans Git/Github ( works ok for personal projects ):Save your files in a sequential format :prototype1_001
prototype3_004Add a comment on each file where you explain what changed from previous files.Save a copy on the cloud (dropbox, google drive),upload to your site via ftp and serve if needed.
If you are a company you might not want or be allowed to host your code on a public facing website or need some other versioning solution that integrates better with your pipeline and specific product.
I just bring up these points in case you have never used these tools and are suddenly feeling you should have, no shame, no biggie, we will hopefully point you in the right direction:
Other resources: Some good places to read up and find alternative on-boarding:Git tutorial: https://www.atlassian.com/gitGithub Documentation: https://help.github.com/articles/set-up-git/Git Documentation: https://git-scm.com/doc
Your specific setup will be somehow different depending on your IDE and what your specific project or organization requires, I use and recommend atom as my editor, it has the advantage of integrating nicely with git/github via plugins.
Besides an editor you will need access to your command line or terminal, git, and github desktop, let’s review:
Note: Depending on your platform your installation will be slightly different, but you will end up with the ability to type git commands from a terminal, consult these instructions: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
Before actually getting started let’s quickly summarize a few ways of interacting with git/github:
Easing into Git and Github with the Desktop App
The easiest way to get started might be via the github desktop app, you can do anything you would via commands through a graphical UI, but be forewarned that it is a crutch you might eventually discard in favor of IDE plugins and terminal commands, especially if you need to become proficient fast.
Terminal Command Line
This is probably the most common way of interacting with github, it does require you to be comfortable with your command line or terminal ( specifically navigating to your projects directory, making files and running commands ).
The most efficient way I've found, but does require some experience and extra setup.
And the website ?
The website is where you will spend about half your time, the reason being that most of the collaborative aspects and granular features live there.
So what to use ?
If you are starting out I recommend the Desktop App + Website for your first experiments, then Terminal + Website and finally aim for IDE + Plugins + all the previous for your day to day progression.
Learning Path :
I like and recommend a learning path based on thoughtful curated experiments you should try and/or analyze on your own followed by a day to day real life example, if you prefer API style learning , just consult git’s and github’s documentation.
1. Creating and initializing a Repo.
If you are joining an existing project this first part ( repo creation ) is already done for you.
A repo, short for repository is simply your code base , we’ll get into the details as needed, for now let’s just start by creating one, we’ll use the website:
- Click the new repository button:
- And fill in the required fields, note that you can specify your repo to be public or private
After this we now have a new repo with a simple readme:
You can find the repo here:https://github.com/KenoLeon/QuickGuideToGitGithub
2. Clone a repo
Once you have a repo to experiment with the next step will be to import it into your computer, this step is called cloning and depending on your setup can be done in a number of ways, let’s examine a couple:
Not much to it, open Github Desktop, and add your repo which can be found in a dropdown list, you also need to specify where your local copy will be:
Cloning via the terminal is a 2 step process, first we need to get the repo’s address from Github’s website.:
Then navigate via your terminal or shell to the local folder ( gitLocal for instance ) and paste your repo’s address along with the git clone command :
$ git clone https://github.com/KenoLeon/QuickGuideToGitGithub.git
IDE Plugins each have their own setup and UI, I am currently using Atom, which includes a tight Github integration by default 🎉
Full Documentation can be found here:https://flight-manual.atom.io/using-atom/sections/github-package/
Cloning with Atom can be done by calling the command on mac…(shift+command + p ) finding the github submenu and selecting clone:
Then just fill in the blanks with your repo’s url and your local folder:
Regardless of which route you took, you will end up with a local folder in your computer which should be an exact replica or clone of the one that lives on Github for you to play with.
Note: If you are cloning a private repo from an organization, chances are they need to authorize you before you can clone it, you might also need to create a token in your local computer for access through SSH, more...https://help.github.com/articles/https-cloning-errors/
3. Stage commit and push.
git processes your files in a very specific way,( the price you pay for keeping things tidy and reversible ), so there is some learning curve.
We can start with a minimal example using atom since the UI makes things easy to follow, but we’ll briefly cover Github Desktop and the terminal soon after…
Adding files to your repo:
- Create a new file in your local repo:
- Add some code:
- At this point atom will add your new file to a list on the git tab:
If you click on it you will see the changes that are about to be staged :
- Right click to stage (or click the stage all if you have many new files):
Your file has moved one step closer to being published ( or pushed ) to your repo on Github:
Once you have staged your file or files it is time to tell git you are ready to incorporate them into your code base, this step is aptly named commit as in commit changes, importantly, in this step you should add a small comment with your relevant changes:
Writing a message every time you commit your changes might seem overkill, especially if you are working solo, but once you add more people or are coding for an organization, this becomes a real time saver, your project lead should tell you what kind of comments to include, there's also plenty of good advice online like the following:https://chris.beams.io/posts/git-commit/
So are we done ? Nope; your staged code and commit(s) are still in your computer, in order to upload them and incorporate them into github, you will need to push them:
Once you push your changes your repo on the Github site will incorporate them, and whoever clones it will get them too:
Clicking on your file reveals the precious code along with a detailed history of changes we will skip for now :
Same same but different:
You can accomplish the same via the Github desktop app, here your changes are staged automatically:
The commit is very similar:
And pushing is also a button click away:
And on the terminal/shell:
Create a new file in your local folder ( hello_world.rb ) and add some code, in your terminal go to your folder :
$ cd gitLocal
$ cd QuickGuideToGitGithub
so far so standard, the first thing we will do is stage or add the file so git tracks changes:
$ git add hello_world.rb
In a similar way committing :
$ git commit -m "Added Hello World in Ruby"Note: -m is an option to the commit command and simply states the following "msg" is the commit message, there are many other options depending on the command, for an overview type :$ git helpAnd for specific commands ( in this case commit ):$ git help commit ( exit by typing q)You can also consult the manual online:https://git-scm.com/docs/git-commit
And pushing :
$ git pushNote: If you have been trying each of the previous examples you might have an error and need to pull first your repo, something we will explain in the next exercise.
Before moving forward let’s quickly recap:
You should now be able to create and initialize repos for your own projects, or if you are joining another project you can clone it.
You can also make changes to your code and stage (or add) the files to your repo, commit and push them, look at you go.
4. Working with branches.
Branches are an important concept in git; a branch while complex in it’s details can be understood simply as a different path your code or project went via changes, additions, deletions etc,etc.
Additionally there is a master branch you should be aware off which signifies the base or starting point for your code to wander, one last thing to note is that you can merge branches, usually into a master branch via a pull request, in practical terms this means you can explore or make some code changes and then figure out if they are worth the inclusion into the project ( usually via reviews from others and pull requests… pr’s for short ), and like everything in git/github it is fully reversible, documented and collaborative, let’s dig in.
In this example we start with a MASTER branch with 2 lines of code, a BRANCH A where one line of code was deleted was explored but was abandoned, another BRANCH B was then made and a 3rd line of code added, it was later merged with Master via a PR.
The exercise part of this small section simply consists in you being aware that there are branches, and that by default, when you create a new repo you will be working on the master branch, you can see this on the website:
Each organization and project has a particular way of dealing with branches, consult your lead or project manager, if you are working on your own project you can even omit working with them.
5. Getting changes.
Let’s say there are 2 people working on a project on the same branch, you make some changes to your local cloned repo and are ready to commit and push, but then you get an error ( here on atom ) stating that there have been changes, and you should pull first.
so you are left with a situation where you would need to first undo your current commit:
Then fetch changes:
And then finally commit your own changes.
On Github Desktop the UI does a nice job of informing you of local and remote changes and what to do about them:
On the terminal, you need 2 commands:
$ git statusThis will return something like:On branch master
Your branch and 'origin/master' have diverged,and have 1 and 4 different commits each, respectively.(use "git pull" to merge the remote branch into yours)
And then you should pull :
$ git pullNote that there is an intermediate operation called fetch which we will cover in the next section.
In general this is what you want to see before starting to work with your code:
$ git status
...On branch master
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
On Github Desktop :
And on Atom ( after clicking fetch ):
It’s unfortunately very easy to forget this last point or arrive at a situation where you are prompted to merge and resolve conflicts, a bit of a pain you will eventually encounter, but hopefully not on your first day, check here if it happens :
Resolving a merge conflict on GitHub - User Documentation
You can resolve simple merge conflicts that involve competing line changes on GitHub, using the conflict editor. ...
Let’s continue our overview…
Day to day ( Collaborative coding with less screw ups )
If you’ve been following along you now have enough knowledge to use git and github on your own, yet we have not gone through the collaborative aspects and how that affects your day to day workflow, let’s say you are a designer or junior coder and it’s your first day…
Let’s also throw in a monkey wrench, everybody is super busy to onboard you and you have no idea where to make your changes, your project tree also looks like this :
So what I would suggest is that a) you get a copy (clone) of the master branch into your local computer, make the changes or additions you need,and b) make a new branch you can present for review when things calm down, here’s the 4 step process ( via the terminal ) :
On your git folder...$ git fetch --allThis gets information on what changed in all the branches of the project...https://www.git-tower.com/learn/git/faq/difference-between-git-fetch-git-pull$ git checkout masterGet changes from master...Use git pull if needed...$ git pullMake a new branch with your name and the feature based on master.$ git checkout -b yourName/NewFeaturePublish your new Branch...$ git push -u origin yourName/NewFeature
Now if you go to Github you will see a new branch that is identical to the Master branch ( at the point in time you checked out and pulled ). This is where you can safely work on your own changes independently from the rest of your team.
The same process can be done via Github Desktop:
First pull changes from master if any:
Then create your new Branch:
Name it :
And publish it:
In Atom after fetching and pulling from master:
And clicking the publish buttons:
Writing Code and saving changes.
So here we finally are, you can now write your code in your own branch and then submit it to revision to your coworkers for review and hopefully inclusion to the master (or production) branch, what will happen next is a pull request, let’s go over this process…
From the top…
$ git statusMake sure you are on the right branchOn branch keno/newCode
Your branch is up to date with 'origin/keno/newCode'.else checkout your branch and check for changes...$ git checkout keno/newCode$ git status
On Github Desktop after you fetch origin…
And on Atom your…
Ok, so you are now on your branch, let’s makes some changes…
On HellowWorld.js fromconsole.log('Hello World');Toconsole.log('Goodbye cruel world');
Stage commit and push. ( on Atom)…
On Github Desktop you should see this:
And commit + Push …
On the Terminal it’s a series of commands that start by asking git for recent changes…
$ git statusChanges not staged for commit:(use "git add <file>..." to update what will be committed)(use "git checkout -- <file>..." to discard changes in working directory)modified: HelloWorld.js
Then stage (add),commit and push.$ git add HelloWorld.js
$ git commit -m "Modified HelloWorld.js"
$ git push
The Pull Request :
The pull request process starts with you doing some changes in your branch and then merging those changes into the master branch, graphically it looks something like this:
Note: Pull Requests are usually done via the website (command line, plugins, etc are more niche).
Importantly, the process has collaborative controls that lets others check on your code in order to prevent the now famous screw up, let’s look at a simple Pull Request ( PR or pr for short ):
The pull request is initiated by going to your branch and clicking the new pull request button, notice your branch is out of sync with master, something quite common, no biggie we’ll deal with that soon.
The pull request screen has a lot of information and features, at the top for instance you have the merge operation ( make sure you are merging into /from the right branch), the bottom lists all the commits you’ve been working on and the right side add collaborative controls, a common one for instance is asking others to review your PR.
Your PR is now ready for review and conflict resolution (if any), let’s resolve conflicts…
In this case someone made changes to the HelloWorld.js without us pulling them into our branch, so we need to decide which ones are the correct ones, you do this by removing the arrows and clicking “Mark as resolved” like so:
You will then be able to merge into the Master Branch…
The result is that the master branch will now have your changes…
One last thing, most projects on Github employ an issues system to keep track of bugs and improvements, you can check the issues list on your project via the issues tab on the site:
Hopefully your project will have less issues, but it is not uncommon to be told on your first day to grab an issue and start working on it or be assigned one, as mentioned there is plenty of nuance and each projects workflow is a little different, but this is as far as I think you should know to get started on your first day or days, the rest you will pick up as you go, do stick around for a few gotchas that might stump you in these first days…
Screw ups ?
So this quick guide at this point might not seem so quick to you and you are right, it’s a lot to take in, but beyond the collaborative and hosted aspects of GitHub, it is when joined to git’s tracking and versioning control that this steep learning curve is justified, this is a fancy way of saying, everything we’ve done up to this point is reversible, so if you screwed up; you (or most likely your team lead ) can go back and unscrew things, it is also fully documented so fingers can be pointed, but here is also where the collaborative aspects kick in and helps prevent screw ups from reaching the master branch via pull requests and reviews.
Starting from scratch every time:
One of the biggest issues I’ve encountered is keeping track of changes on the master branch while working on multiple issues plus changes in your local environment, the following works in a sort of brute force way since it throws away your local changes and makes your local branch even with master, can also be used whenever you are not sure you’ve fallen out of sync or have merge issues, but be aware it is destructive in nature so I’d recommend you experiment a bit with these techniques on a dummy repo…
$ git fetch --all
$ git checkout master
$ git reset --hard origin/master
$ git checkout user/feature# You now have the latest changes from Master on your local remote branch and can make changes..$ git commit -am "Feature"
$ git push origin HEAD# You replaced your remote branch with the above changes...# Make pull request
If you want to completely overwrite your local and remote branch with master…
$ git fetch --all
$ git checkout user/feature
$ git reset --hard origin/master
$ git pushBoth your local and remote branches will have the contents of master.
The issue with the previous 2 examples is that you will loose whatever you were working on in your local branch and it dirties up git’s timeline, an alternative exists in the form of git stash which at it’s most basic works like this:
$ git stash Saves the state of your working directory state.$ git apply Restores whatever you were working on.
I recommend you experiment with stashing changes before using it as it is a more advanced subject but will help you in the long run, here’s the docs:
Depending on how many projects or repos your project or organization uses, and how hectic your day to day is, it might be a good idea to become a git expert, reading the book is a good start.
I hope this guide helps you with your project on-boarding, I should mention that it is by no means a definite, complete or probably effective guide for some, but just my take on it, if you have a better one or want to suggest additions or corrections, please let me know in the comments.
Good Luck !
About the Author :
Born Eugenio Noyola Leon (Keno) I am a Designer, Developer-Programmer, Artist and Inventor, currently living in Mexico City, you can find me at: www.k3no.com