Codecademy Logo

Learn Git II: Git for Deployment

Print Cheatsheet

A GitHub README File

Adding a README file to your GitHub repository is the best way to introduce your project to others. Since it is usually the first thing others see on your repository, it is the best place to explain what your project does, why it’s useful, and how they can get started with it.

Comic with three panels in which a character clones a GitHub project, gets confused trying to use it, and finally realizes after three hours that there’s a README file explaining all of the steps

Writing a Good README file

A good README file in GitHub, at minimum, contains the following elements:

  • Title
  • Description
  • Features
  • How to use
  • Technologies
  • Collaborators
  • License

You can further level up your README file with markdown:

  • Use headers and HTML to format your README and make it easier to read.
  • The headers automatically generate a table of contents on GitHub!
  • Use media, such as images and videos, to make your project look more appealing.
An image of a README on GitHub showing table of contents for the project called "My Awesome Project". The headers include "What does it do?", "Usage" with a "Requirements" subsection, and "License".

The Main Branch

In Git, the main project is completed on the main branch. Making your first commit in a new git repository will automatically create a main branch. Create new branches from the main branch to develop new features for a project. These branches can be merged into main at a later time to incorporate the new features. You can use git branch to check what branch you’re on.

$ git init
Initialized empty Git repository in /home/ccuser/new-project/.git/
$ echo "Hello World!" >> hello.txt
$ git add hello.txt
$ git commit -m 'initial commit'
[master (root-commit) bb0e565] initial commit
1 file changed, 1 insertion(+)
create mode 100644 hello.txt
$ git branch
* master

Creating a New Branch

In Git, the git branch branch-name command is used to create a new branch called branch-name. Branches should be named something that describes the purpose of the branch.

Note that branch names can’t contain whitespace: new-feature and new_feature are valid branch names, but new feature is not.

Run git branch new-feature to make a new branch called new-feature

Viewing the Current Branch

In Git, the git branch command will display all of the branches. The current branch will display * before its name.

git branch displays the two branches "fencing" and "master".  "master" is preceded by an asterisk.

Merge Conflicts

In Git, a merge conflict occurs when the same file is changed on the current branch and the branch that is being merged. An error will appear displaying: CONFLICT (content): Merge conflict in [filename].

Git will automatically edit the file with the conflict to show where the conflict is. The current branch’s text will be between <<<<<<< HEAD and =======. The text from the branch that is being merged into the current branch will be between ======= and >>>>>>> branch-name

To resolve a merge conflict, edit the file with the conflict, decide which parts of each branch’s edits should be kept, then add and commit the file.

PETE PAN
<<<<<<< HEAD
Address: No 31 Kensington Hill Park, London, England
=======
Address: 113 Gloucester Rd Patchway, Bristol, England
>>>>>>> resume-edits
-------------------

Deleting a Branch

In Git, the git branch -d branch_name command is used to delete the branch_name branch. It’s good practice to delete a branch after it has been merged into the master branch.

git branch -d new-feature will delete the branch with the name "new-feature"

Merging Branches

In Git, the git merge branch-name command will add the changes from branch-name into the current branch. Use this command when you have finished building a feature in a separate branch and want to bring those changes into your current branch.

git merge resume-edits brings the changes from resume.txt into the master branch

Git Collaboration Workflow

A common Git collaboration workflow is:

  1. Fetch and merge changes from the remote
  2. Create a branch to work on a new project feature
  3. Develop the feature on a branch and commit the work
  4. Fetch and merge from the remote again (in case new commits were made)
  5. Push branch up to the remote for review

Steps 1 and 4 are a safeguard against merge conflicts, which occur when two branches contain file changes that cannot be merged with the git merge command.

List the Git Remotes

In Git, the git remote -v command returns a verbose list of remote repositories that the current project is tied to.

  • Git lists the name of the remote repository as well as its locations.
  • Git automatically names this remote origin, because it refers to the remote repository of origin. However, it is possible to safely change its name.
  • The remote is listed twice: once for (fetch) and once for (push).
$ git remote -v
origin /home/ccuser/workspace/curriculum/science-quizzes/ (fetch)
origin /home/ccuser/workspace/curriculum/science-quizzes/ (push)

Pushing Branch Changes

In Git, the git push origin branch-name command pushes the branch, and all committed changes, to the remote. This branch can now be reviewed by collaborators.

In the example, the current branch containing the committed changes is called bio-questions.

$ git push origin bio-questions
Counting objects: 3, done.
Delta compression using up to 16 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 392 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To /home/ccuser/workspace/curriculum-a/science-quizzes
* [new branch] bio-questions -> bio-questions

Cloning a Remote Repository

In Git, the git clone remote_location clone_name command creates a local copy of a remote repository.

  • remote_location tells Git where to find the remote repository and can be a filepath or web address.
  • clone_name is the name of the directory where the remote repository’s contents will be copied.

In the example, my-quizzes is a new directory created as a local copy of the science-quizzes Git project. Committing changes to my-quizzes will not impact science-quizzes.

$ ls
science-quizzes
$ git clone science-quizzes/ my-quizzes
Cloning into 'my-quizzes'...
done.
$ ls
my-quizzes science-quizzes

Fetching Remote Origin Changes

In Git, the git fetch command downloads objects from the origin remote repository. The changes, however, are not merged into the current branch-name branch. Instead, they are stored in the origin/branch-name branch, waiting to be merged.

In the provided example, using the git branch -a command to see the existing branches, we can see that fetched data has been stored in a new origin/master branch.

$ git branch -a
* master
$ git fetch
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (5/5), done.
From /home/ccuser/workspace/curriculum-a/science-quizzes
* [new branch] master -> origin/master
$ git branch -a
* master
remotes/origin/master

Git Remote

A remote is a shared Git repository that allows multiple collaborators to work on the same Git project from different locations. Collaborators work on the project independently and merge changes together when they are ready to do so.

Merging Fetched Changes

In Git, the git merge origin/branch-name command will merge fetched changes, stored in origin/branch-name to the current branch-name branch.

In the example, master is the name of the branch being merged.

$ git merge origin/master
Updating 2fd7d9b..3a29454
Fast-forward
biology.txt | 4 ++++
1 file changed, 4 insertions(+)
create mode 100644 biology.txt