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?
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
This is equivalent to:
git branch 3.3.1_foo_bug_fix git checkout 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
- 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
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
In order to make a pull request, first you must be sure you have commits pushed to your fork. Once you have done this, visit the repository in question (CONNECT, Common-Types, CONNECT-Webservices) and visit the Pull Requests Tab.
Once at the Pull Requests tab you will see a list of all Open pull requests, as well as the option to create a new one via the "New Pull Request" button.
Upon clicking the "New Pull Request" button you will be taken to a change comparison page between 2 branches. You will need to 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 CI is responsible for running tests on the CONNECT_integration branch before everything is pushed to master. This ensures that the code works as intended and does not introduce any broken features. Once you have selected your repository, you must then select the branch that contains your changes you wish to integrate. Once you do so, the changes should be listed on the page and will show any addition and deletions to the code base. If you are comfortable with these changes, press the "Create pull request" button.
At this point the PR should be reviewed by other peers. If a peer feels changes may be needed they should submit a review of "Request Changes" and list any changes and a reason for why the change is requested. Once everyone has submitted an Approval review, the changes may be merged into the repository.