Before reviewing this page, you should be familiar with concepts of version control and distributed version control systems. See /wiki/spaces/CONNECTWIKI/pages/8585251 for information and links.

Cloning the Repository

• How do I clone the CONNECT git repository?

  Code Block
  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?

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

  
  

• How do I "switch" to the 3.3.1 branch?

  Code Block
  git checkout 3.3.1

  
  

• How do I branch and checkout using one line?

  Code Block
  git checkout -b 3.3.1_foo_bug_fix 3.3.1

  This is equivalent to:

  Code Block
  git branchcheckout 3.3.1_foo_bug_fix git checkout -b 3.3.1_foo_bug_fix

  
  

• How do I delete a local branch?

  Code Block
  git branch -d 3.3.1_foo_bug_fix

  
  

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

  Code Block
  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?

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

  
  

• How do I delete a remote tag?

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

  
  

• How do I delete a remote branch?

  Code Block
  git push origin :<name of branch to delete>

  
  

• How do I create a new branch and push to remote?

  Code Block
  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?

  Code Block
  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?

  Code Block
  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)?

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

History

• 
  

• How do I view the git history of a filework with a remote branch or other fork of CONNECT?

  Code Block
  git log --follow EntityNotifySoapHeaderHandler.xml

  How do I see what was committed in a given revision?

  Code Block
  git log -p <commit hash>

• How do I view a specific revision of a file?
   

  Code Block
  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?

git reset --hard

To revert a single file or deleted directory, do:

git checkout HEAD <FILE>

Reverting

• Halp! 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

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

...

• 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?

  Code Block
  git log --follow EntityNotifySoapHeaderHandler.xml

  
  

• How do I see what was committed in a given revision?

  Code Block
  git log -p <commit hash>

  
  

• How do I view a specific revision of a file?
   

  Code Block
  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?

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

  
  

• How do revert all my changes?

  Note
  title Warning
  This will delete all your changes as no backups are created!

  
  

  Code Block
  git reset --hard

  
  

• To revert a single file or deleted directory, do:

  Code Block
  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

  Code Block

  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?

  Code Block
  git status

  
  

• Show all files that have been modified and not staged as a list

  Code Block
  git diff --stat

  
  

• Diff between what is staged and what has been committed

  Code Block
  git diff --staged

  
  

• Ignore blank and white spaces diff

  Code Block
  git diff -b -w --staged

  
  

• Filter the diff: ignore deleted files

  Code Block
  git diff --diff-filter=ACMRTUXB --staged

  
  

• How do I see the diff between my branch against a previous revision

  Code Block
  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.

  Code Block
  git stash save "GATEWAY-123: Stuff"

  
  

• View all your stashes (i.e. the stash stack)

  Code Block
  git stash list

  Sample Output:

  Code Block
  stash@{0}: On 3.3.1: GATEWAY-123: Stuff

  
  

• Apply a stash to your branch. This example applies the stash 0.

  Code Block
  git stash apply --index stash@{0}

  
  

• Drops a stash from the stack. This will delete it.

  Code Block
  git stash drop stash@{0}

  
  

• Show a diff of a particular stash from the stack.

  Code Block
  git stash show -p stash@{0}

  
  

Committing and Pushing to Github

• How do I get the latest from remote? This will merge the changes from the remote repository to your branch.

  Code Block
  git pull

  
  

• How do I stage all my modified files for later commit?

  Code Block
  git add . git add -u (updates)

  
  

• How do I stage a subset of my modified files for later commit?

  Code Block
  git add <file1> <file2> <etc.>

  
  

• How do I commit everything that has been staged?

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

  
  

• How do I push my commits to the remote repository?

  Code Block
  git push origin <remote branch name>

  
  

Sample Push to Github

akong@plain:~/Workspace/connect/Current/Product$ git push originstatus
# On branch 3.3.1
# Username:Changes Password:to Countingbe objectscommitted:
66,# done. Delta compression(use using"git upreset 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):

1. /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.
2. ~/.gitconfig file: Specific to your user. You can make Git read and write to this file specifically by passing the --global option.
3. 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:

...

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):

1. /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.
2. ~/.gitconfig file: Specific to your user. You can make Git read and write to this file specifically by passing the --global option.
3. 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:

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.

Image Added

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).

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.

Image Added

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.