How to Work with Git

Simple workflow: How to work with Git

Configuration: Only do this once, or if you delete your folder, or if you're on a new machine.

1. Always fork the repository (repo) you are working on.

   • This is accomplished by logging into Github and selecting Fork near the top right of the repo.

2. Clone your fork down to your local machine:

   • From your fork click on the Clone button and copy the git URI to your clipboard.
   • Open terminal/shell/powershell/cmd, navigate to your preferred project directory, and git clone <the URI on your clipboard>.
   • Change into the directory with the files you cloned.

3. Before you start working add a pointer to the ISLE repo you forked.

   • From OUR repo click on the Clone button and copy the git http URI to your clipboard.
   • In terminal/shell/powershell/cmd enter git add remote ISLE <the URI on your clipboard>.

Make certain your master is even with ISLE's master

4. STOP! Get up-to-date before you do anything, fetch your remotes to the most recent commits:

   • Change into the directory with the files you cloned.
   • In terminal/shell/powershell/cmd enter git fetch --all.

5. Checkout and pull the ISLE master to your master:

   • Checkout your master: git checkout master
   • Pull the ISLE master into yours (so you're up-to-date): git pull ISLE master
   • Push your master BACK to Github if you saw a fast-forward: git push origin master
     • If you saw a non-fast-forward and a merge message appears: there were differences in your branches. Never work on master.

Create a topic/fix/enhancement/document branch for your work, and have at!

6. Create your branch and check it out:

   • Create a branch with: git branch <some helpful and identifying name> where some helpful name is, for example: "git branch documentation-update".
   • Checkout your new branch with git checkout <some helpful and identifying name>, for example "git checkout documentation-update".

7. Start your work and commit ("save your work") at times (read: more than once, likely) that feel logical

   • Create logical checkpoints (i.e., commits) when you feel you've finished on a particular "part" of your work. E.g., you've just created a new file and added some stubbed content: commit it!
     • Commits are references in your work and can be helpful if you need to go back to an earlier version of your work (like an undo). By committing regularly you give yourself utmost flexibility and it's a good practice/habit.

8. Creating commits:

   • In terminal/shell/powershell/cmd enter git status to see a list of files changed, added, and removed.
   • Use git add <file> or git rm <file> to stage (add or remove) files from your commit. If you want to add all files to the commit you may shorthand it with git add -A (i.e., git add all).
   • Create your commit after files are staged: git commit and enter a commit message that is helpful for you and us! Helpful hint: always write in the present tense: "Update <somefile.ext> to include all of the appropriate modules."
   • Continue your work, going through this step as many times as needed.

Finalizing and preparing for a pull request (PR).

9. Pushing back to origin will update Github:

   • After your final commit and feel you're ready to PR back to ISLE: git push origin <name-of-your-branch>.
   • Visit your forked Github repo and switch branches to your new branch.
   • Select "New pull request" (top-left) and tell Github, if it isn't already, to compare against remote branches. Select ISLE Master first, then your repo and branch.

10. Create the PR and send it:

    • Enter a description of what your commits do in sum total.
    • How should this be tested?
    • Who should be notified? @mention them if you know.
    • Is there anything else we should know before we review and test your work?
    • With your description complete click the "Create Pull Request" button and you're done! Thank you!