Introduction to the Git Workflow - PTC-ALM/TortoiseSI GitHub Wiki

This documentation is written for users who have knowledge of source control systems, but limited exposure to Git and assumes the following:

• the user has no write access to PTC-ALM/TortoiseSI and must fork this repository and submit pull requests to contribute to the PTC-ALM/TortoiseSI repository.
• the user is working primarily with git through the command-line tools (although suggestions are given for GUI-based tools, the use of which can mostly be derived from the steps in this documentation).

More advanced Git users may have more optimal workflow practices, and may deviate from these steps as appropriate.

The official Git documentation can be found here.

Required:

• Git - make sure you have Git Bash and Git GUI

Optional:

• Source Tree - a free Git client for Windows/Mac. A much nicer GUI than Git’s bundled one.
• TortoiseGit - an open source Windows Shell Interface to Git based on TortoiseSVN

Note: these instructions presume that the command-line (Git Bash) is being used. Doing the same operations in the GUI tool of your choice should be fairly straight-forward.

1. If you do not have a local repository setup to work on and you do not have the "Collaborator" permissions on PTC-ALM/TortoiseSI, you will need to fork the PTC-ALM/TortoiseSI repository to your own repository. On the PTC-ALM/TortoiseSI GitHub page, click the “Fork” button on the top right and fork this to your local repository i.e. select @<your user name> when asked where to fork this repository. You should now see /TortoiseSI in GitHub. If you are a "Collaborator" for PTC-ALM/TortoiseSI, you do not need to fork the repo since you have the permissions to push directly to PTC-ALM/TortoiseSI. In this case, skip to step 2.

2. Create a directory for your local git repositories, say in D:/git, referred to as your top-level git directory.

3. If you are not a collaborator, copy the clone URL from GitHub on your <your user name>/TortoiseSI GitHub page. If you are a collaborator, copy the clone URL from the PTC-ALM/TortoiseSI GitHub page.

4. Open Git Bash and navigate to your top-level git directory and enter the following to clone the repository to D:/git/TortoiseSI:

   git clone <clone url>

where is the clone URL copied in step 3.

5. Now if you forked the TortoiseSI repository in step 1, you should configure remotes for your forked TortoiseSI repository. Otherwise, you can skip this step. Currently ‘origin’ points to /TortoiseSI, as shown by the output of this command:

   <localuser>@<machine name> /d/git/TortoiseSI (master)

   $ git remote -v

   origin https://github.com/<GitHubUsername>/TortoiseSI.git (fetch)

   origin https://github.com/<GitHubUsername>/TortoiseSI.git (push)

We want to add a new remote called ‘upstream’ that points to the PTC-ALM repository so we can keep our fork in sync with the PTC-ALM repository (note: make sure that you are adding the clone URL for PTC-ALM/TortoiseSI, not the /TortoiseSI clone URL!):

`<localuser>@<machine name> /d/git/TortoiseSI (master)`

`$ git remote add upstream https://github.com/PTC-ALM/TortoiseSI.git`

After running above, make sure that the remotes are appearing correctly in your list of remotes:

`<localuser>@<machine name> /d/git/TortoiseSI (master)`

`$ git remote -v`

`origin  https://github.com/<GitHubUsername>/TortoiseSI.git (fetch)`

`origin  https://github.com/<GitHubUsername>/TortoiseSI.git (push)`

`upstream        https://github.com/PTC-ALM/TortoiseSI.git (fetch)`

`upstream        https://github.com/PTC-ALM/TortoiseSI.git (push)`

Your fork operation essentially creates your ‘master’ branch. Ideally, this should be kept clean and in sync with ‘upstream’. When working on an issue, it is best to work on a branch of your local ‘master’. Let’s say you have been assigned to work on issue #4. Make sure you are at the top level of your TortoiseSI git repository (say D:/git/TortoiseSI) and create a new branch with a name of your choosing:

`git checkout –b iss4`

This will create a branch in your local TortoiseSI repository called ‘iss4’ and switches you to that branch. Your Git Bash prompt should show you what branch you are on (git status –v works, too):

`<localuser>@<machine name> /d/git/TortoiseSI (iss4)`

`$`

You are now ready to start committing changes on your issue branch.

You can see changes in files in the repository by running the git status command. The output of this also gives some useful information on what commands you potentially need to run. New files need to be added before they can be commited (the git add command) and tracked by Git. Use the git commit –m to record changes to the repository with a commit message. The –a option tells the command to automatically stage files that have been modified and deleted, but new files that have not yet been added will not be affected.

• https://help.github.com/articles/syncing-a-fork/ To sync ‘iss4’ with ‘upstream’, run these commands:

  $ git fetch upstream (fetch ‘upstream’ branches & their respective commits)

  $ git checkout master (switch to local branch ‘master’)

  $ git merge upstream/master (sync local ‘master’ with ‘upstream’ master branch)

  $ git checkout iss4 (switch back to ‘iss4’ branch)

  $ git merge master (merge ‘iss4’ with local ‘master’ branch)

Note, if you have changes in your branch and you attempt to checkout master, you may get an error, asking you to either commit your changes or stash them if you don’t want to commit what you’ve been working on before you switch branches. To stash your changes, do git stash, follow the commands above to merge with the upstream master, checkout your branch, and run git stash pop or git stash apply (applies most recent stash, unless you specify a stash, see results of git stash list). Unlike pop, the apply option does not drop the stashed work from the stash. To remove it, run git stash drop with the name of the stash to remove.

`git pull origin master`	(fetch and merge from origin to current branch)

You now have working code in your branch that you want to go to the ‘upstream’ repository. For your code changes to get merged, you will need to create a pull request for the PTC-ALM/TortoiseSI repository to pull in your changes from the /TortoiseSI repository.

1. Make sure all your changes have been committed (git commit -m) on your issue branch ‘iss4’.

2. Push your branch (with your committed changes) to a new remote branch.

   git push origin iss4:issue4 (push changes in iss4 branch to new origin remote branch issue4)

3. Go to the PTC-ALM/TortoiseSI GitHub page and create a pull request.

4. You will be taken to the Pull Request Creation Page:

5. First, change the head fork to your public repository (/TortoiseSI). Choose the appropriate remote branch for your head fork (i.e. if we did git push origin iss4:issue4, then the branch should be issue4). Then, make sure the base fork is PTC-ALM/TortoiseSI (not TortoiseGit/TortoiseGit). Set the base of the base fork to ‘master’.

   • “Base”: where your changes should be applied
   • “Head”: what you think should be applied

6. Fill in Pull-Request details as appropriate. Indicate which issue your pull request will fix by adding markup to the Comment Box (if you enter “#” you should be able to select you issue from a pop-up list of available issues).

7. Click “Create pull request” on the right to submit your pull request for review.

Checking out pull requests locally:

• See https://help.github.com/articles/checking-out-pull-requests-locally/
• Useful if you want to test pull requests locally before merging
• Anyone can work with a previously opened pull request
• Note that depending on your setup (your remotes, do git remote -v) you may want to do git fetch upstream pull/ID/head:branchname

(that is, fetch from ‘upstream’ rather than ‘origin’) to merge the pull request into a new branch in your fork from the ‘upstream’ repository, PTC-ALM/TortoiseSI. ‘Origin’ is likely pointing to /TortoiseSI, and the pull request does not exist for this repository.