Cloning the Repository

How do I clone the CONNECT git repository?

git clone https://github.com/CONNECT-Solution/CONNECT <desired path>

Branching and Tagging

What is a good reference on git's branching and merging mechanism, and explanation of workflow?
Pro Git book section on basic branching and merging.

How do I see all my branches?

git branch (local only)
git branch -r (remote only)
git branch -a (all)

How do I "switch" to the 3.3.1 branch?
```
git checkout 3.3.1
```

How do I branch and checkout using one line?

git checkout -b 3.3.1_foo_bug_fix 3.3.1

This is equivalent to:

git checkout 3.3.1
git checkout -b 3.3.1_foo_bug_fix

How do I delete a local branch?
```
git branch -d 3.3.1_foo_bug_fix
```

How do I create a new "foo" tag on the "bar" branch?

git checkout bar
git tag "foo"
git push origin tag "foo"

How do I create a new "foo" tag on a specific commit on the "bar" branch?

git checkout bar
git tag -a "foo" <commit hash> -m "<tag message>"
git push --tags

How do I delete a remote tag?

git tag -d <tag name>
git push origin :refs/tags/<tag name>

How do I delete a remote branch?

git push origin :<name of branch to delete>

How do I create a new branch and push to remote?
```
git checkout <name of branch to base from>
git branch <new branch name>
git push -u origin <new branch name>
```
The -u switch will automatically configure git to push and pull from the remote branch. You can leave off the -u switch if you don't want git pull to merge the remote branch to your local.
How do I see which local branch is tracking which remote branch?
```
git remote show origin
```
How do I create a branch called 3.2.2_dev based off of a 3.2.2 branch from the server?
```
git checkout -b 3.2.2_dev remotes/origin/3.2.2
```

How do I work with a tag based off of a branch (e.g. 3.2.2_RC2 tag based off of 3.2.2 branch)?

git checkout 3.2.2      # checkout base branch
git pull                # get latest remote base branch
git checkout 3.2.2_RC2  # checkout tag

How do I work with a remote branch or other fork of CONNECT?

git remote add connect_official https://github.com/CONNECT-Solution/CONNECT.git   # Add the repo to your remotes. Arguments are: git remote add <alias> <URL>
git fetch connect_official                                                        # Fetch the changes so you can pull and checkout
git remote -v																	  # List all of your remote repositories.
git checkout connect_official/CONNECT_integration                                 # If you wish to check out the branch entirely
git pull connect_official/CONNECT_integration                                     # Or if you wish to pull these changes into your own branch instead

History

How do I view the git history of a file?

git log --follow EntityNotifySoapHeaderHandler.xml

How do I see what was committed in a given revision?
```
 git log -p <commit hash>
```

How do I view a specific revision of a file?
```
git show <commit-ref>:<filename>
```
The <commit-ref> in the command can be the SHA-1 value or the HEAD

^ (one previous commit) shortcut.

Cleaning

How do I clean up all the unknown files in my workspace?

git clean -f -d
git clean -f -d -X (remove ignored files as well)

How do revert all my changes?
Warning

This will delete all your changes as no backups are created!
```
git reset --hard
```
To revert a single file or deleted directory, do:
```
git checkout HEAD <FILE>
```

Reverting

Help! I accidentally committed and pushed a file to github! How do I revert it?
Like subversion, you have to revert the file locally and then commit it. The <commit-ref> in the command below can be the SHA-1 value or the HEAD

^ (one previous commit) shortcut. Afterwards, you should see the specified filename be in the index, and you can commit it like any other changes.

git checkout <commit-ref> -- <filename>

Sample revert

akong@plain:~/Workspace/connect/Current/Product/SoapUI_Test/ValidationSuite$ git checkout 4cf2f12f9659c4022d4c0740955da81b6ee1fb93 -- 2-EndToEndSelfTest_g1-soapui-project.xml

akong@plain:~/Workspace/connect/Current/Product/SoapUI_Test/ValidationSuite$ git status
# On branch 3.3.1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#    modified:   2-EndToEndSelfTest_g1-soapui-project.xml
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#    ../../Production/global-groovy.log
#    ../../Production/soapui-errors.log
#    ../../Production/soapui.log

Diff-ing

How do I see what changes there are in my current working set?
```
git status
```
Show all files that have been modified and not staged as a list
```
git diff --stat
```
Diff between what is staged and what has been committed
```
git diff --staged
```
Ignore blank and white spaces diff
```
git diff -b -w --staged
```

Filter the diff: ignore deleted files

git diff --diff-filter=ACMRTUXB --staged

How do I see the diff between my branch against a previous revision
```
git diff HEAD^ HEAD
```
Each ^ represents one previous revision, so HEAD^^ means two previous revisions. Equivilant to ^ is ~. HEAD~ is the same as HEAD^, and HEAD~3 is the same as HEAD^^^.

Stashing

Stash all your changes. This will stash all your modifications in the stash stack and revert back your branch to its original state.
```
git stash save "GATEWAY-123: Stuff"
```

View all your stashes (i.e. the stash stack)
```
git stash list
```
Sample Output:
```
stash@{0}: On 3.3.1: GATEWAY-123: Stuff
```

Apply a stash to your branch. This example applies the stash 0.
```
git stash apply --index stash@{0}
```

Drops a stash from the stack. This will delete it.
```
git stash drop stash@{0}
```
Show a diff of a particular stash from the stack.
```
git stash show -p stash@{0}
```

Committing and Pushing to Github

Empty Directories

Git will not push an empty folder into the repository, so add an empty .gitignore inside if you need them.

How do I get the latest from remote? This will merge the changes from the remote repository to your branch.
```
git pull
```
How do I stage all my modified files for later commit?
```
git add .
git add -u (updates)
```
How do I stage a subset of my modified files for later commit?
```
git add <file1> <file2> <etc.>
```

How do I commit everything that has been staged?

git commit -m "commit message including Jira issue number"

How do I push my commits to the remote repository?
```
git push origin <remote branch name>
```

Sample Push to Github

akong@plain:~/Workspace/connect/Current/Product$ git status
# On branch 3.3.1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#    modified:   Production/Common/CONNECTCoreLib/src/main/java/gov/hhs/fha/nhinc/docregistry/adapter/AdapterComponentDocRegistryOrchImpl.java
#    modified:   Production/Common/CONNECTCoreLib/src/main/java/gov/hhs/fha/nhinc/docrepository/adapter/dao/DocumentDao.java
#    modified:   Production/Common/CONNECTCoreLib/src/main/java/gov/hhs/fha/nhinc/docrepository/adapter/model/DocumentQueryParams.java
#    new file:   Production/Common/CONNECTCoreLib/src/test/java/gov/hhs/fha/nhinc/docregistry/adapter/AdapterComponentDocRegistryOrchImplTest.java
#    modified:   SoapUI_Test/ValidationSuite/2-EndToEndSelfTest_g0-soapui-project.xml
#    modified:   SoapUI_Test/ValidationSuite/properties/2-EndToEndSelfTest_g0-soapui-project.properties
#

akong@plain:~/Workspace/connect/Current/Product$ git commit -m "GATEWAY-1952: Added ondemand support for QD/DocRegistry adapter"
[3.3.1 04b656e] GATEWAY-1952: Added ondemand support for QD/DocRegistry adapter
 6 files changed, 392 insertions(+), 83 deletions(-)
 create mode 100644 Product/Production/Common/CONNECTCoreLib/src/test/java/gov/hhs/fha/nhinc/docregistry/adapter/AdapterComponentDocRegistryOrchImplTest.java

akong@plain:~/Workspace/connect/Current/Product$ git status
# On branch 3.3.1
# Your branch is ahead of 'origin/3.3.1' by 1 commit.
#
nothing to commit (working directory clean)

akong@plain:~/Workspace/connect/Current/Product$ git push origin 3.3.1
Username:
Password:
Counting objects: 66, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (27/27), done.
Writing objects: 100% (36/36), 7.43 KiB, done.
Total 36 (delta 16), reused 0 (delta 0)
To https://github.com/CONNECT-Solution/CONNECT.git
   1b68a6d..04b656e  3.3.1 -> 3.3.1

Git Configuration

Git configuration can occur in three separate files.

From the Pro Git Book (open source):

/etc/gitconfig file: Contains values for every user on the system and all their repositories. If you pass the option` --system` to git config, it reads and writes from this file specifically.
~/.gitconfig file: Specific to your user. You can make Git read and write to this file specifically by passing the --global option.
config file in the git directory (that is, .git/config) of whatever repository you’re currently using: Specific to that single repository. Each level overrides values in the previous level, so values in .git/config trump those in /etc/gitconfig.

On Windows systems, Git looks for the .gitconfig file in the $HOME directory (C:Documents and Settings$USER for most people). It also still looks for /etc/gitconfig, although it’s relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.

Creating Aliases

This section details how to create aliases in git. Aliases are useful for common commands such as checkout, status, and branch.

Open a command prompt that has access to git. Git has a global config file call .gitconfig. It may be useful to a person to read up on git configuration, but this section will deal only with adding aliases.

We do this by running 'git config --global alias.foo command'. What follows the '.' is the shortcut, followed by the command.
Lets say you want to shorten the 'checkout' command. An example of how to do this would be:

git config --global alias.co checkout

Now running the command:

git co 3.3.1

This will be the equivalent of

git checkout 3.3.1

Here is a list of common shortcuts:
co = checkout
br = branch
ci = commit
st = status
branches = branch

Commits and Rebasing

How do I update my branch with the latest from origin/CONNECT_integration AND push it to my fork?

git checkout my-feature
git fetch origin
git merge origin/CONNECT_integration
git push my-alias <fork's branch>

How do I create a local branch that is tracking another branch from somebody else's fork?

git remote add <fork>
git checkout -b yourNewBranch
git pull <fork> <fork's branch>

How do I rebase?

In the example below, we rebase the my-feature branch with the CONNECT_integration before we push. This will make your history look like you did your changes from the latest CONNECT_integration head instead of the one that you branched off from when you created your my-feature branch.

git checkout my-feature
<Do all your commits>
git rebase origin/CONNECT_integration
git push my-alias <branch>

Rebasing is safe as long you follow this rule:

NEVER REBASE AFTER A PUSH

So rebase only before you are ready to push. Rebasing changes the commit hash due to the process of your commits effectively being undone, and repeated off of the HEAD of the branch you rebase, so be mindful when you attempt to rebase.

Pull Requests (PR)

First, make sure that your commits have been pushed to your fork. Then, visit the repository in question (CONNECT, Common-Types, CONNECT-Webservices) and go to the Pull Requests Tab.

On the Pull Requests tab, there will be a list of all open pull requests. There is also an option to create a new one via the New Pull Request button.

Creating a new Pull Request

Upon clicking the New Pull Request button, a change comparison page will be shown between the 2 branches. Click the "compare across forks" hyperlink in order to show a separate repository (this should be your fork off of CONNECT) for your comparison. The base repository should be CONNECT-Solution/<Project> and the base branch should be "CONNECT_integration" for the CONNECT project (or "master" for both Common-Types and CONNECT-Webservices).

You should never merge directly into the master copy when merging into the CONNECT project, as our Continuous Integration (CI) is responsible for running tests on the CONNECT_integration branch before everything is pushed to master.

These tests ensures that the code works as intended and does not introduce any broken features. Once you have selected your repository then select the branch that contains your changes you wish to integrate. The changes will then be listed on the page and show any additions and deletions to the code base. Once, you are comfortable with these changes, press the Create pull request button.

At this point the PR should be code reviewed by other peers. If a peer feels changes are needed they will submit a review of "Request Changes". This review will list any changes and a reason for why the change(s) is requested. Once everyone has submitted an Approval review, the changes may be merged into the repository.

Merge the Pull Request

In order to merge the PR, you must select one of the 3 options: Create a merge commit, Squash and merge, or Rebase and merge. The default of these options is “Rebase and merge” which will rebase your commits to replace them at the end of the HEAD commit on the base branch. Creating a merge commit will simply merge the commits into the base branch. Squash and merge will condense all the commits in the PR into a single commit, and merge them into the base branch. Once you have decided on which of the 3 merges you wish to use, select the option and click the merge button. The changes will then be merged into the base branch and the PR will be closed.

CONNECT Wiki

Git Commands