GitHub is only as powerful as our ability to harness git! Remember, git is the underlying technology that actually tracks our changes, saves our commits, and stores our branches. GitHub, on the other hand, is an incredibly powerful web interface and cloud-hosting platform that allows us to store our git repositories remotely and collaborate with a community of over 3.5 million developers worldwide with additional tools and views.
In this module, there are two ways to complete it. You can either complete it using the GitHub Desktop Application or the terminal/gitbash. It is recommended that those without command line experience start with the GitHub Desktop version. Experienced developers or those looking for a challenge are encouraged to try working with git on the command line.
As always, this module can be experienced in multiple ways:
- Youtube video available using GitHub Desktop here.
- Command Line video coming soon!
- Full text of the course is available below.
If you do not already have a repository, or you are not using a repository that already exists, you must create one! For the purposes of this course, we are not creating a repository, but we will go over the steps. Repositories are a great way to keep code together for classes or projects, so you'll definitely be creating some on your own as you work GitHub into your personal workflow.
To create a new repository, go to your GitHub homepage and select "New Repository". The only thing you need to create your repository is a name. Remember, much like branch names, repository names do not have spaces. You may choose to add a description, but this is not necessary. You can also select whether your repository should be public or private on this page. This determines whether or not people can view your repository without your express permission. If you have signed up for the GitHub Student Developer Pack in Module 0, then you have unlimited private repositories, so feel free to use them when you feel it necessary.
Finally, you have the option to add a README, a license, and a .gitignore file to your repostiory:
- A README is a markdown file that renders automatically on GitHub. You will notice that assignments in this repository use READMEs to display instructions without you having to manually open a file. READMEs are great for installation instructions, announcements, or any other information any visitor to your repository may need.
- A .gitignore file contains files, directories, and file types that exist in your project repository but should not be committed. A great candidate for a .gitignore is any generated file, like .class and .jar files in Java applications. These files are recreated every single time NetBeans compiles a project, and committing them just takes up more room and can potentially cause merge conflicts. GitHub has several template .gitignore files to choose from for many popular languages and frameworks, including Java.
- A license file describes what users are and are not allowed to do with your repository. Technically, a project on GitHub is not open source unless the license specifically gives permission for users to view, fork, and modify said code. There are several great license templates available on GitHub, and GitHub created this useful guide to help you choose the one right for you. For something like basic code written for a class, consider the Unlicense Academic, which releases your code completely into the public domain but has specific language disallowing users from using your code to cheat.
Once you've made your selection, choose "Create repository" and you are good to go!
Now that you have a repository, in this case, the github-traning repository, you should clone it to your local machine so that you can work on it! It is important to remember two key concepts with your cloned repository, remote and local.
- Remote: an internet-accessible copy of your repository that is treated as an authoritative source of that repository. In this case, your remote is GitHub!
- Local: a full copy of your repository cloned to a personal computer to be worked on.
GitHub Desktop automatically creates a subdirectory of "Documents" called "GitHub", where it clones all of your repositories, we will follow the same convention with both GitHub Desktop and the command line.
From your repository homepage, click "Clone or download" and choose "Open in Desktop".
- From your repository homepage, click "Clone or download", copy the link to your clipboard.
- Open terminal or Git Bash. If you do not already have a "~/Documents/GitHub" directory, run
mkdir ~/Documents/GitHub - Now, run
cd ~/Documents/GitHubto change your active directory to your GitHub directory. - Run
git clone [paste-link here]to clone your repository inside your GitHub directory. - IMPORTANT you MUST run
cd [github-repository-name]after cloning before you can run any git commands!
Remember, our "master" branch is a clean, "release-worthy" branch of our highest-quality code. Now, when you are working on your own repository where you are the sole contributor and you are just working on a simple homework assignment, it may not be necessary to use individual branches. For working in this repository, as well as any other well-maintained public repository, you cannot commit directly to the master branch, and therefore must make a working branch. For this module, we will name your working branch "[GitHub Username]-module2".
For both of these methods, you MUST carefully select a base branch. For example, in Dr. Bryant's COMP167 class, major programs are divided into levels. You must complete each level on a separate branch, and submit them via a pull request. Now, if you complete level-1, but your pull request hasn't been merged yet, your code is not on your "master branch". In order to start working on level-2 right away, you must create your level-2 branch with a base branch of level-1. However, in most other situations, "master" will be your base branch.
- Click "Branch -> New Branch" with your repository selected.
- Give your new branch a name.
- Select base branch from the "From" drop-down menu.
- If you are not already there, run
cd ~/Documents/GitHub/[your-repository-name]to C hange D irectory to your repository. - If you are using "master" as your base branch, run
git checkout master, or else checkout whatever branch you'd like to use as your base branch. - Now run
git pullto make sure your base branch is up to date before continuing. - Create a new branch using
git checkout -b [new-branch-name].
Now, when it's time to make changes, you simply open the files you cloned in your text editor of choice! Make changes and save them just like you'd usually work on code. If you are creating a new project in an IDE, make sure you place this project inside your repository, not the default save location for that IDE. For example, NetBeans will try to save all new projects in "/Documents/NetBeansProjects/", but if you are using git in COMP163 or COMP167, you will want to set your project location to "/Documents/GitHub/[Repository-Name]". Finally, once changes have been made, you must tell git to track these changes and add them to your staging area for a commit.
Changes are automatically added to tracking in GitHub Desktop.
The easiest way to add all files to tracking is git add .. The period in this case refers to the current working directory on the command line, so this adds all changes within the current directory to tracking and stages them for commit.
Once your changes have been saved, you wrap up these changes in a "commit" so that git can add them to the project history. You should commit often enough that you can describe what each commit does in a single concise sentence. For example "Override toString method", "Implement getters/setters", "Create UIViewController class". Notice that these commit messages are given in the imperative voice, which means they explain what the commit will do, they don't talk about what they've done. The reason for this is quite simple: when working on git, you should be committing changes to a working branch, not the "master" branch. Given that the "master" branch is considered the shipping version of your code, any code not in master isn't technically done just yet, so saying "Overrode toString method" or "Implemented getters/setters" isn't actually accurate yet! Writing in the imperative voice gives a concise summary of changes in a commit message that clearly tells the reviewer what a pull request WILL DO if merged.
Simply add a concise description in the "Summary" block. You can add a description if you'd like, but it isn't required and often isn't necessary.
git commit -m "[Your commit message here]"
The more often you push, the better. One rule is certain, before you close your laptop or sign off of a desktop, you should definitely push your changes to your remote. This adds any changes you made on a given branch locally to the remote version of that branch. You should do this whenever you are getting ready to leave a computer in case you need to continue work on another computer, or if something physically happens to the computer you were working on previously.
You should also pull at the start of each development session, and any time you check out a new branch, to make sure you are working on the most up to date version of that branch. A pull operation consists of two parts: fetching the remote version of your current branch and merging it in to your local verison. This is generally handled behind the scenes without the user needing to add more control.
Make sure that the branch you would like to pull or push is selected on the "Current Branch" drop-down menu, then:
- Click "Repository -> Pull"
- Click "Repository -> Push"
First, you must make sure you are currently on the branch you want to pull or push, you can check this by running git branch and can change branches using git checkout [branch-name]. Then,
git pullgit push
Often, especially on projects including two or more developers, the "master" branch may be updated since you created your working branch. If you remember from Module 1, we must merge those changes into our working branch in order to make sure we are continually working on the most up to date version of our code.
- Checkout your "master" branch and pull the most recent version.
- Checkout the branch that you'd like to update using the "Current Branch" drop-down menu. Click "Branch -> Update From Default Branch".
git checkout mastergit pullgit checkout [branch-to-update]git merge master
Using your chosen git client (command line or GitHub Desktop), clone this repository, create a new working branch, and create a file called "git-quiz.md" in "submissions/[Your-username]/module-2". Answer the following questions in your file:
- How often should you commit, when working in git?
- How often should you push, when working in git?
- Did you decide to use GitHub Desktop or the command line to complete this exercise?
- How will you commit and push these changes using your chosen method?
Push these changes and open a pull request in the github-training repo.