New to git? Follow the steps below to get comfortable making changes to the code base, opening up a pull request (PR), and merging code into the primary branch. Any important git and GitHub terms are in bold with links to the official git reference materials.
Step 0: Install git and create a GitHub account
The first two things you'll want to do are install git and create a free GitHub account.
Follow the instructions here to install git (if it's not already installed). Note that for this tutorial we will be using git on the command line only. While there are some great git GUIs (graphical user interfaces), I think it's easier to learn git using git-specific commands first and then to try out a git GUI once you're more comfortable with the command. A note: 95% of other online git resources and discussions will also be for the command-line interface.
Once you've done that, create a GitHub account here
Git and GitHub
A quick aside: git and GitHub are not the same thing. Git is an open-source, version control tool created in 2005 by developers working on the Linux operating system; GitHub is a company founded in 2008 that makes tools which integrate with git. You do not need GitHub to use git, but you cannot use GitHub without using git. There are many other alternatives to GitHub, such as GitLab, BitBucket, and “host-your-own” solutions such as gogs and gittea. All of these are referred to in git-speak as “remotes”, and all are completely optional. You do not need to use a remote to use git, but it will make sharing your code with others easier.
Step 1: Create a local git repository
When creating a new project on your local machine using git, you'll first create a new repository (or often, 'repo', for short).
To use git we'll be using the terminal. If you don't have much experience with the terminal and basic commands, check out this tutorial (If you don’t want/ need a short history lesson, skip to step three.)
To begin, open up a terminal and move to where you want to place the project on your local machine using the cd (change directory) command. For example, if you have a 'projects' folder on your desktop, you'd do something like:
mnelson:Desktop mnelson$ cd ~/Desktop mnelson:Desktop mnelson$ mkdir myproject mnelson:Desktop mnelson$ cd myproject/
To initialize a git repository in the root of the folder, run the git init command:
mnelson:myproject mnelson$ git init Initialized empty Git repository in /Users/mnelson/Desktop/myproject/.git/
Step 2: Add a new file to the repo
Go ahead and add a new file to the project, using any text editor you like or running a touch command. 'touch newfile.txt' just creates and saves a blank file named newfile.txt.
Once you've added or modified files in a folder containing a git repo, git will notice that the file exists inside the repo. But, git won't track the file unless you explicitly tell it to. Git only saves/manages changes to files that it tracks, so we’ll need to send a command to confirm that yes, we want git to track our new file.
mnelson:myproject mnelson$ touch mnelson.txt mnelson:myproject mnelson$ ls mnelson.txt
After creating the new file, you can use the git status command to see which files git knows exist.
mnelson:myproject mnelson$ git status On branch master Initial commit Untracked files: (use "git add <file>..." to include in what will be committed) mnelson.txt nothing added to commit but untracked files present (use "git add" to track)
An interlude: The staging environment, the commit, and you
One of the most confusing parts when you're first learning git is the concept of the staging environment and how it relates to a commit.
A commit is a record of what changes you have made since the last time you made a commit. Essentially, you make changes to your repo (for example, adding a file or modifying one) and then tell git to put those changes into a commit.
Commits make up the essence of your project and allow you to jump to the state of a project at any other commit.
So, how do you tell git which files to put into a commit? This is where the staging environment or index come in. As seen in Step 2, when you make changes to your repo, git notices that a file has changed but won't do anything with it (like adding it in a commit).
To add a file to a commit, you first need to add it to the staging environment. To do this, you can use the git add command (see Step 3 below).
Once you've used the git add command to add all the files you want to the staging environment, you can then tell git to package them into a commit using the git commit command.
Note: The staging environment, also called 'staging', is the new preferred term for this, but you can also see it referred to as the 'index'.
Step 3: Create a commit
It's time to create your first commit!
Run the command git commit -m "Your message about the commit"
mnelson:myproject mnelson$ git commit -m "This is my first commit!" [master (root-commit) b345d9a] This is my first commit! 1 file changed, 1 insertion(+) create mode 100644 mnelson.txt
The message at the end of the commit should be something related to what the commit contains - maybe it's a new feature, maybe it's a bug fix, maybe it's just fixing a typo. Don't put a message like "asdfadsf" or "foobar". That makes the other people who see your commit sad. Very, very, sad. Commits live forever in a repository (technically you can delete them if you really, really need to but it’s messy), so if you leave a clear explanation of your changes it can be extremely helpful for future programmers (perhaps future you!) who are trying to figure out why some change was made years later.
Step 4: Create a new branch
Now that you've made a new commit, let's try something a little more advanced.
Say you want to make a new feature but are worried about making changes to the main project while developing the feature. This is where git branches come in.
Branches allow you to move back and forth between 'states' of a project. Official git docs describe branches this way: ‘A branch in Git is simply a lightweight movable pointer to one of these commits.’ For instance, if you want to add a new page to your website you can create a new branch just for that page without affecting the main part of the project. Once you're done with the page, you can merge your changes from your branch into the primary branch. When you create a new branch, Git keeps track of which commit your branch 'branched' off of, so it knows the history behind all the files.
Let's say you are on the primary branch and want to create a new branch to develop your web page. Here's what you'll do: Run git checkout -b . This command will automatically create a new branch and then 'check you out' on it, meaning git will move you to that branch, off of the primary branch.
After running the above command, you can use the git branch command to confirm that your branch was created:
mnelson:myproject mnelson$ git branch master * my-new-branch
The branch name with the asterisk next to it indicates which branch you're on at that given time.
Step 5: Create a new repository on GitHub
If you only want to keep track of your code locally, you don't need to use GitHub. But if you want to work with a team, you can use GitHub to collaboratively modify the project's code.
To create a new repo on GitHub, log in and go to the GitHub home page. You can find the “New repository” option under the “+” sign next to your profile picture, in the top right corner of the navbar:
After clicking the button, GitHub will ask you to name your repo and provide a brief description:
When you're done filling out the information, press the 'Create repository' button to make your new repo.
GitHub will ask if you want to create a new repo from scratch or if you want to add a repo you have created locally. In this case, since we've already created a new repo locally, we want to push that onto GitHub so follow the '....or push an existing repository from the command line' section:
mnelson:myproject mnelson$ git remote add origin https://github.com/cubeton/mynewrepository.git mnelson:myproject mnelson$ git push -u origin master Counting objects: 3, done. Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) To https://github.com/cubeton/mynewrepository.git * [new branch] master -> master Branch master set up to track remote branch master from origin.
(You'll want to change the URL in the first command line to what GitHub lists in this section since your GitHub username and repo name are different.)