Lesson Weekend

When we work on a development project as a collaborator, we have commit privileges to the master repository on GitHub. The development workflow for collaborators in a team takes advantage of some Git functionality that we don't often use on pair projects: Branching and merging. Below is a general outline of this workflow. Use this lesson as a reference when working on your group project this week:


Git Team Workflow

1. Setup Github Repo

Build a repo on Github and add all team members as collaborators. Clone the GitHub master repo to each pair's desktop with $ git clone <repo-url>. Navigate to the project with $ cd <project-directory-name>.

2. Create Branches

Each pair creates (and switches to) their own feature branch locally by running $ git checkout -b <branch-name>. Note that repos come with a master branch by default; you will not need to create one manually.

Tip: If you're ever uncertain which branch you're currently on, run $ git branch

3. Code

Pairs complete work on their own branches, adding and committing throughout the process.

4. Pull Origin Master into Local Master

Before pushing work, pairs pull any new code teammates may have merged into the Github master branch (AKA origin master or remote master) into their local master branch.

This is done by navigating into local master with $ git checkout master, then running $ git pull origin master. This pulls code from Github's master into the local master.

Generally speaking, this command triggers one of the following three results:

Example A - Pulling down no new changes. There is no new content to pull into the local branch, it is already up-to-date.

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
$ git pull origin master
From https://github.com/test-user/my_project
 * branch            master     -> FETCH_HEAD
Already up-to-date.

Example B - Pulling down new changes with no merge conflicts. There was new content from the Github's master (also known as origin master), but Git was able to merge it into the branch automatically.

$ git checkout master
Switched to branch 'master'
$ git pull origin master
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/test-user/my_project
 * branch            master     -> FETCH_HEAD
   2833d6c..51f2f03  master     -> origin/master
Updating 2833d6c..51f2d03
Fast-forward
 README.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Example C - Pulling down new changes with merge conflicts. There was new content from the Github's master, but Git was not able to merge it into the branch automatically. The user will need to do so by hand.

$ git checkout master
Switched to branch 'master'
$ git pull origin master
From https://github.com/test-user/my_project
* branch            master     -> FETCH_HEAD
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.

5. Resolve Conflicts (if necessary)

If conflicts occur (as seen in Example C above), conflict tags will appear in the impacted files:

...
<<<<<<< HEAD
   This is code from the local master branch!
=======
   This is code from the origin master branch!
>>>>>>>
....

Content above the ======= refers to code from the branch you wish to update (in this case, local master). Content below comes from the branch that is not being updated (in this case, Github's master). Resolve these conflicts by replacing everything between <<<<<<< and >>>>>>> with the code you ultimately want in the project's 'final draft' or master. Then remove conflict tags, and commit the changes.

6. Merge Local Feature into Local Master

After gathering the most up-to-date code from master origin, ensure code in the local feature branch works correctly with code from the master branch by merging feature branch into local master.

Confirm you're still located in your local master branch by running $ git branch. Then, merge local feature into local master with $ git merge <feature-branch-name>. If any merge conflicts occur, follow the steps above.

7. Add Local Master Code to Origin Master

Pairs ensure the application still looks and functions correctly. When/if everything works as desired, local masters code may be added to origin master.

There are two primary ways to do this. If all of the collaborators for a project are not physically present to review code, then it is best practice to submit a Pull Request via GitHub so that each member has a chance to review the changes before any new code is added. If all collaborators are present and approve of the changes to the code, or if you are working solo, then it is acceptable to merge into master directly and push the updated master to Github.


If all collaborators are not present (most common):

Pull Requests

a. Push Branch to Github

Feature code has been merged into local master branch successfully, and any subsequent refactoring committed. Push this to GitHub as the new feature branch by running $ git push origin <branch-name>.

b. Pull Request

A pull request is created by navigating to the feature branch on Github, selecting "New Pull Request" , clicking "Create Pull Request", and including a description of new features in the resulting form. Finally, "Create Pull Request" will create and send the request to project collaborators.

c. Review and Merge

Repo owners and collaborators may then view this notification for more information, and options to merge the request into master. More information on that is available here.


If all collaborators are present, and have okay'd changes, or you are working solo:

Merge to Master

a. Merge Feature into Master

Feature code has been merged into the local master branch successfully, and any subsequent refactoring committed. Contents of local master are then pushed directly into origin master by switching to master with$ git checkout master, and merging the appropriate feature branch into master with $ git merge <branch-name>.

Again, the result should be very similar to one of the code snippets listed in Step 5. If examples A or B are received, there is either nothing new to merge or new code was merged automatically. If something akin to example C is received, pairs must repeat Step 6 in order to resolve any merge conflicts.


8. Delete

If merging was successful, the feature branch may be deleted if it is no longer in use. The easiest way to do this is through the GitHub repo. Simply visit the repository, and select the "branches" option:

branches-option-in-github-repo

Then, in the "branches" area of your GitHub repository, select the red delete icon next to the branch your group would like to delete:

delete-option-in-github-repo


A visual representation of this branching/merging workflow:

Git in Teams

Group Project Workflow


Do rely upon this cheatsheet until you've read the full text of this lesson at least once, which provides important considerations and context for this process.

1. Setup Github Repo

  • Create GitHub repo..
  • Add all members as collaborators as explained in the Git With Collaborators: Setup.
  • Clone to each pair's machine with $ git clone <repo-url>.

2. Create Branches

  • Each pair creates (and switches to) a local feature branch with $ git checkout -b <branch-name>.

3. Code

Pairs complete work on dedicated branches.

4. Pull Origin Master into Local Master

When ready to add feature branch code to master, first ensure feature code works with master code.

  • Navigate to local master with $ git checkout master
  • Pull code from GitHub master into local master with $ git pull origin master.

5. Resolve Conflicts (if necessary)

If you receive a Git message reading Automatic merge failed; fix conflicts and then commit the result. you must manually fix conflicts:

  • Locate conflict tags in relevant files. (Message will list affected files.) Content above the ======= is code from branch we're merging into. Below ======= is branch we are getting new code from.
  • Replace everything between the <<<<<<< and >>>>>>> with code wanted in finalized master.
  • Remove the conflict tags, thoroughly test everything works, commit.
  • Repeat for all files containing conflicts.

6. Merge Local Master into Local Feature

Always double-check master code works with feature code on the feature branch (not master).

  • Navigate into local feature with $ git checkout <local-feature-branch>.
  • Merge local master into local feature with $ git merge master.
  • If conflicts occur follow instructions above.

7. Add Local Feature Code to Origin Master

Submit new code to master branch via pull request on GitHub, or merging into master directly:

Pull Requests

  • Push feature branch to GitHub with $ git push origin <branch-name>.
  • Navigate to the feature branch on Github, select New Pull Request. Complete and submit form.
  • Collaborators are notified of PR. May review and merge as detailed here.

Merge to Master

  • Confirm master has been merged into local feature and everything works.
  • Navigate to local master with $ git checkout master.
  • Merge code from feature into master with $ git merge <feature-branch>

8. Delete

After successful merge feature branch may be deleted if no longer in use.

Other Git Commands


For reference, here are other commonly-used Git commands you may require throughout project development:

Configurations

  • $ git config --global user.name "[name]": Sets the user name for all commits.
  • $ git config --global user.email "[email address]": Sets the email for all commits.
  • $ git config --global color.ui auto: Adds useful color to the command line output.

Repositories

  • $ git init: Creates a local repository in the current directory.
  • $ git clone [url]: Downloads a remote repository from the URL and all of its version history in the current directory.

Changing Version History

  • $ git add .: Adds ALL files with changes to the staging area to be committed.
  • $ git add [file]: Adds the named file to the staging area for committing.
  • $ git reset [file]: Unstages the file, but all changes are kept.
  • $ git commit -m "[message]": Records all of the staged files permanently to the version history; message should describe the changes finishing the phrase "This commit will…". Example: $ git commit -m "add AJAX functionality to the comments form"

Reviewing Version History

  • $ git log: Lists commit history for the current branch.
  • $ git status: Lists the files where changes have been made to be committed.
  • $ git diff: Shows differences in files that are not yet staged.
  • $ git diff --staged: Shows differences between the staged file(s) and the last version(s) of the file.
  • $ git diff [branch-1]...[branch-2]: Shows content differences between branch-1 and branch-2.

Branches

  • $ git branch: Lists current branches with an asterisk by the current branch.
  • $ git checkout [branch-name]: Switches to the branch, branch-name.
  • $ git checkout -b [branch-name]: Creates and checks out a new branch named branch-name.
  • $ git branch -D [branch-name]: Delete the branch named branch-name.
  • $ git merge [branch-name]: Merges branch-name version history into the current branch.

Remotes

  • $ git remote: lists currently associated remote repositories.
  • $ git remote add [remote-name-alias] [url]: Adds a new remote repository with the name remote-name using the URL of the remote repo on github.
  • $ git push [remote-name-alias] [branch-name]: Pushes the branch (branch-name) to a remote repository (remote-name-alias).
  • $ git pull [remote-name-alias] [branch-name]: Pulls the latest changes from a remote repository to a local branch repository (e.g. git pull origin master).