Using GitKraken with FHIR
GitKraken is a cross-platform tool that offers a graphical user interface to work with Git. This topic provides documentation for getting started committing to the FHIR spec with GitKraken.
First, download and install the latest version of GitKraken: https://www.gitkraken.com/
Once you have the GitKraken client installed, you'll need to clone the FHIR repository locally. A clone is a local copy of the repository that you can use. Git is a distributed source control system, which means that each copy of the repository can manage its own set of changes.
NOTE: For SVN users that already have a local checkout, do not clone into that directory. Instead, create a new directory for the Git clone.
To clone the repository, first, copy the repository URL from the main page of the repository:
Next, go to GitKraken, select "Clone Repo" from the "File" menu and paste the url into the "Url" textbox. The dialogbox allows you to change where the local copy will reside. Start cloning by clicking "Clone the repo".
Note that this will create a sub-folder with the same name as the repository (fhir in this case) within the directory specified in the "Where to clone to" textbox, so you do not need (nor should you) create that directory yourself.
You will do your work on your own "feature branch", which is a branch of the main branch, normally called "master". Before you commence work on a bug or new feature, you will need to make sure our local copy has the latest changes coming in from other authors on that master branch. Obviously, if you have just cloned a repository, you will already have the latest changes.
To update your local copy with master, right click on the "master" branche and select "Pull (fast-forward if possible)" (since this will "pull" the other author's changes from the github server into your own copy):
This will display the pull dialog:
GitKraken will integrate the changes with your local copy, and show a dialog reporting success when done in the right upper corner of your screen:
If the pull fails, you will see this:
Note that GitKraken mentions "merge conflicts" in this dialog. When this happens while you are doing a pull, this means that you have accidentally been making local changes directly on the master branch, and not on your own feature branch. If you follow the instructions in this document this should never happen.
Once you have an up-to-date local copy, making changes to the spec involves:
- Creating a local "branch"
- Committing the changes to your local repository
- Pushing your changes to Github
- Creating a pull request
First, create a local branch with a descriptive name. Right click on the repository folder and select "Create branch...":
This will display the "Create branch dialog":
Enter the name of the branch, brynrhodes-cdsresources-qa in this case, and check the "Switch to new branch". Then click okay and you TortoiseGit will create the branch and switch to it:
Note: Creating a branch in Git is a very lightweight operation, all it really does is remember where you were in the commit log when you created the branch.
Once you have made your local changes and verified that they build locally, you need to commit your changes to your local repository. Right click on the repository folder and select Git Commit -> "branch name", where "branch name" is the name of your feature branch:
This will open the Commit dialog, showing a list of the files that you have changed in your working directory:
By default, any files that are modified will be selected. Add a commit message, typically starting with GF#XXXX: where XXXX is the number of a GForge tracker item that covers the change you are making. In this case, we're just making some QA updates, so there isn't an associated GForge tracker.
NOTE: The "Not Versioned Files" section lists files in your directory that aren't part of the repository. For example, if you've added a new file, you have to tell Git about it in order to include it in the commit. Make sure you include any files you've added, otherwise they won't be in the commit and they won't make it to the remote repository, usually resulting in a build failure.
Once you're happy with the commit, press the Commit button to start the commit process:
Once you've successfully committed your changes to your feature branch in your local repository, they need to be pushed to the remote repository. From a successful commit, you can start this process by selecting the "Push" button displayed in the above dialog, but you can also always execute a Push from the TortoiseGit right click menu. The Push dialog lets you choose what you want to push:
This dialog allows you to "push" changes from a local branch to a remote branch in the remote repository. Initially, the Remote: branch is empty (because this is a new feature branch that currently only exists in your local repository). What we want to do is create the same branch in the remote repository, so copy the name of your Local branch and paste it into the Remote branch. Also, be sure to check the "Set upstream/track remote branch" option, this tells Git that you want these two branches to be "the same", so that the next time you commit changes to this branch locally, Git will by default know where they should be pushed.
Leave the rest of the options set to their defaults and select OK to start the push:
Once your feature branch is pushed to the remote repository, you'll need to submit a "Pull Request" (often shortened to just PR) in order to request that your changes be reviewed and merged into the master branch. Although you can do this with the TortoiseGit client, the GitHub user interface is a bit more user friendly, just navigate to the repository main page and look for the banner indicating the branch was just pushed:
Click the "Compare & pull request" button to create a pull request for your feature branch:
Click the "Create pull request" button and your pull request is submitted!
Once you've submitted a pull request, the change will be reviewed and merged into the master branch. Before making any additional changes, you'll need to switch back to the master branch. To switch, right click on the repository folder and select "TortoiseGit|Switch/Checkout..."
This will bring up the "Switch" dialog to let you choose the branch you want to switch to:
Select the master branch, leave the rest of the options as they are, and click OK:
This "switches" you back to your local master branch.
NOTE: This means the changes you just made on your feature branch are no longer in your working directory, they are in a pull request that needs to be reviewed and merged into master. Once the change has been merged to the master branch, use "Pull" to get those changes into your local repository's master branch.