Skip to content

Latest commit

 

History

History
233 lines (220 loc) · 6.58 KB

git-tutor.adoc

File metadata and controls

233 lines (220 loc) · 6.58 KB

Git Tutor

1. Git Setup

  1. Create github account

  2. Add your SSH public key via Settings → SSH Keys → Add SSH Keys

  3. Paste your public key (ssh-key-gen if you need one)

  4. Install git on Linux:

    yum -y install git

    Or for macOS:

    brew install git
  5. Configure git

    git config --global user.name "Your Name Comes Here"
    git config --global user.email [email protected]
    git config --global color.branch auto
    git config --global color.diff auto
    git config --global color.interactive auto
    git config --global color.status auto
    git config --global push.default simple
  6. Add this to your ~/.bashrc to provide branch detail when in a git repo

    export PS1="[\u@\h \W\$(git branch 2> /dev/null | grep -e '\* ' | sed 's/^..\(.*\)/{\1}/')]\$ "
  7. Load your ~/.bashrc to enable the new prompt. This will only be active in a git directory (not yet).

    source ~/.bashrc

2. Git Workflow

The following diagram give a general sequence of steps that occur in a typical workflow.

Git Workflow
Figure 1. Git Workflow

2.1. Fork a repo

  1. Fork the repo in github (top right): https://github.com/cloud-practice/git-tutor

  2. Clone your forked repo. You can get the SSH url from your github repo page on the right side, it will be similar to:

    git clone [email protected]:{YOUR_GITHUB_USERNAME_HERE}/git-tutor.git
  3. Change to the directory of the newly cloned repo. You should now be in the directory for the local repository you cloned which should have {master} at the end of the prompt. This indicates you are in a git repo and are in the master branch. Note that this is your local master branch.

    cd git-tutor
  4. Add a remote called upstream to point to the original repository that was forked. A remote is simply any other repository that contains the same - or modified versions of - the same repository. In this case we are added the upstream repo since we don’t have write access to it. We will make changes to our fork and notifiy upstream of our changes. This is called a Pull Request and will be discussed later.

    git remote add upstream [email protected]:cloud-practice/git-tutor.git
    Note
    The remote name of upstream can be any name you like, but is the a common nommenclature. However, you can also add other remotes for colleagues working on the same repository in case you need to send a pull request to them.

2.2. Development Workflow

  1. Create a branch. A branch is essentially copy of master that contains a set of related changes to the original code. Think of a branch as very quick and easy way to test some changes out. If it works, great - you can submit a pull request. If not, just abandon it and return to master which will be untouched. With this in mind, branches should be used extremly generously. It is better to use branches more often than not. It is best practice to leave master untouched and instead experiment in branches.

    git branch <YOUR_BRANCH_NAME>
  2. Check the branch out to begin working on it

    git checkout <YOUR_BRANCH_NAME>
  3. Make changes. For this lab add your github username to the file "completed.lab"

    echo "YOUR_GITHUB_USERNAME">> completed.lab
  4. Check what files were modified

    git status
  5. Test changes and verify

    git diff
  6. Add files that will be committed

    git add completed.lab
  7. Commit changes

    git commit
    Note
    The commit message should provide meaningful information and use the imperative, present tense: "change", not "changed" or "changes". Think of it in terms of completing the imperative statement "This commit will do the following if it is applied as a patch: ". The commit message should fill in the blank. e.g. "fix compile errors in chapter 2".
  8. It is good practice to pull the latest upstream to make sure there will be no merge conflicts. This command tells git to fetch the latest code from upstream from the branch master into your current branch.

    git pull --rebase upstream master
  9. If there are no conflicts, push to a remote branch on your origin (your github fork)

    Note
    If there are merge conflicts see below
    git push origin <branch name>
  10. Go to github.com and initiate a pull request

    Note
    Usually github will detect the change and offer a "Compare and Pull Request" button, but sometimes you may need to select the dropdown that is defaulted to "master" and change to the branch that was pushed and click on "pull request", or just initiate a new pull request from the menu on the right side.

2.3. Update your origin (fork)

This is the same step recommended before a push, replicated here for master

  1. Change to your local master branch

    git checkout master
  2. Update your master branch

    git pull --rebase upstream master
  3. Now update your origin (github fork) with the latest change from upstream

    git push origin master

2.4. Resolving a Merge Conflict

A merge conflict can occur for many reasons. Typically it is when you make a change to the same line that someone else changes but their change was merged first, so git can’t automatically determine what to do. This is relatively easy but must be manually addressed.

  1. If a rebase or merge results in a conflict, use a diff/merge tool such as vimdiff or gvimdiff. If you do not have one installed do so

    For Linux:

    yum -y install vim-enhanced vim-X11

    For macOS:

    brew install macvim
    Note
    You may need to install Xcode first.
  2. Use mergetool to bring up the conflicting files for inspection

    git mergetool
  3. The display will be divided into 4 main areas

    Table 1. Merge Conflict Review Panes in {g,}vimdiff

    upstream version

    common content

    branch version

    unresolved conflicts

    1. Top left = upstream version of the file

    2. Top right = your branch version of the file

    3. Top middle = content between the two files that is the same

    4. Bottom = unresolved conflicts to handle

  4. Make changes to the bottom pane and save and quit. With vim or gvim it is

    :wqa
  5. Add modified file(s). In this case it would likely be

    git add completed.lab
  6. Commit the change

    git commit
  7. If the conflict was a result of a rebase conflict, continue the rebase and make sure everything merges

    git rebase --continue
  8. Push the commit to your remote branch

    git push origin <YOUR_BRANCH_NAME>