GIT Features

To get started using GIT you should create a remote repository, we currently support Azure GIT, GitHub and GitLab, other GIT repositories can be used but have not been tested. Once you have created your remote repository you will be able to configure the GIT connection in DATASTAR.

Connection Settings

Select the Version Control button from the menu and select the GIT repository provider from the drop down list. This will bring up the connection settings for that connection type. Please note DATASTAR does not currently support SSH connections, therefore you must use HTTPS.

1564166388560

Server URI - this should be set to the https address for the repository, most providers will show this address in the via the "clone" option when browsing the site. (SSH connections are not supported).

Authentication - Selecting "Windows Authentication" will used Default Credentials for the connection, "Password Authentication" will use the username and password as Secure Credentials.

Author/Committer - The author is the one who created the content, and the committer is the one who committed it. When you do a normal commit, you are both.

When you have connected you should see a GIT icon in the bottom right hand status bar, this may include a yellow warning triangle if the local working folder is not recognized as a GIT repository. This would be expected if you haven't yet cloned a remote repository.

Clone

When you click the clone button a dialog will be displayed where you can select the branch to clone and the local folder where your workspace will be located. Note the local directory must be an empty folder, you cannot clone into a folder that contains files and folders.

1564167952733

Once the clone has been competed, if it is a new workspace then a ".ds" folder will have been created containing the workspace settings, this folder and it's contents should be committed and pushed to the remote repository so that it is available to other users of the repository.

You can configure the workspace settings by navigating to the "File" tab and clicking the "Workspace" item in the left hand menu. See the Getting Started section on how to configure the settings.

Project Tracking

The Project Tracking option on the Version Control menu group will be enable when using GIT. This is where you configure DevOps task tracking tools so that you can associate changes with tasks. The main benefit of using the task tracking features is that it becomes very easy to then create deployments using the task and provides history, transparency and auditing of a particular change. Currently Azure Dev Ops (Work Items) are supported as well as Rally from CA Technologies.

NOTES - The association to a task is established when you commit a change, however this should not be applied to the task tracking system until the change is pushed to the remote repository. For this reason "GIT Notes" are used to keep track of the task associated with a commit. The notes are pushed to the remote repository when you "push" your changes so that the task references will be visible to other users when they bring in fetch your changes.

AZURE

Azure Dev Ops only supports certain link types for example "Commit" but this must be an Azure Dev Ops GIT repository. "GitHub Commit" links in the Azure Dev Ops Project Settings (refer to Microsoft documentation to set this up) is not currently supported by the Web Service API, this will be added in a future release. For any other GIT repository the commit links will be stored in a "commits.txt" file attached to the work item.

RALLY

When using Rally you must have defined the repository as described in the Getting Started section.

IMPORTANT

Please be aware that tasks associations will not be created and notes will not be pushed if you use other GIT Client Software, therefore if you want this behavior please use DataStar to commit and push changes.

Fetch

When you do a fetch, the changes from the remote repository will be obtained and stored in a separate location from your local repository. So fetch allows you to see the incoming changes without applying them. To fetch changes go to the Incoming view, when first opened it will fetch a list of incoming changes and display them with the associated task if present. Each commit is shown as a separate row which can be expanded to show the files that were changed. Hovering over the commit shows some context sensitive information including the Commit, Author, Date and Comment. A fetch can be run at anytime by using the fetch button, it does not bring the changes into your workspace and therefore it cannot result in a merge conflict. Likewise Notes can be fetched separately via the "Fetch Notes" button.

There are compare options available via the right hand mouse button:

Diff - The diff option provides a diff of the commit and therefore requires the commit row to be selected for the option to be enabled.

Compare - The compare option provides a compare of a specific file and therefore a row within the expanded commit must be selected for the option to be enabled. As with any compare feature you must have enabled the external compare tool via the configuration tab.

1564221613005

Pull

Pull will download latest changes from the remote repository and automatically merge those changes in the local repository. It doesn’t give you a chance to review the changes and as a result conflicts might occur (and they often do). One important thing to keep in mind is that pull will merge only into the current working branch. Other branches will stay unaffected.

Important - if you have an uncommitted change, and you try an pull changes that impact the same file you will get a conflict error, however this will not appear in the list of conflicts as you have not yet committed your change. To resolve this you should commit or revert your change, if you commit then the incoming changes will be merged or a conflict raised that can then be resolved.

1564225196364

Merge

GIT excels at is merging code lines. GIT is so good at this that most of the times the merges just work, so you need to be aware that when you "Pull" changes and there are changes to the same file that you are working on, GIT will automatically merge the changes without raising a conflict. You will know that this has happened as you will see a commit in the "Outgoing" view created by GIT with the message "Merge branch...". There may be occasions when GIT cannot automatically merge changes in which case it will generate a conflict and will not allow an automatic merge.

You will find some strange markers being added to the file in conflict for example <<<<<<< HEAD and >>>>>>> master. These markers were added by Git, giving information regarding which line of the file is related to the conflict. This must be manually fixed as described in the section below on Conflicts.

Push

Before pushing your changes you should check whether there are any incoming changes that need to be pulled into your branch, you cannot push changes to the remote if your branch is behind the tracked remote branch. If you try and push changes in this scenario you will get an error message:

1564223947744

This error message can be resolved by going to the "Incoming View" and pulling the latest changes into your branch, this can result in a merge conflict which can then be resolved before pushing your changes.

Conflicts

An advantage of using version control to manage your files is that several people can work concurrently on a file. One drawback is that sometimes you must resolve conflicts before you can check in your files. If your commit fails you will get an error message.

You can manage the conflict via the "Conflict" option in the Version Control ribbon menu. This will bring up a list of items that are in conflict.

1563746535306

The right hand mouse button context menu has the following options:

Merge Selected this will merge the files manually using the merge tool that you have configured in the Configuration Options, this option is only available where the merge tool is configured, good candidates for the merge tool are BeyondCompare or KDiff3.

1563745242805

You will notice that this will generate multiple versions of the file, named "ours", "base", "theirs", these will be opened in your merge tool, it is your job to review the changes so that the actual file reflects the desired content. When the main file is saved the conflict is automatically marked as resolved and the "ours", "base", "theirs" files will automatically be deleted.

Keep Ours this will overwrite the incoming version with the local version of the file.

Keep Theirs this will overwrite the local version with the incoming version.

Stash

Let’s say you are in the middle of implementing a new feature and you need to switch branches to fix a bug or revert back to where you started in the current branch. You don’t want to commit half-done work or lose your changes. Stash is a handy feature for these types of situations. It takes your changes, saves them to a temporary place and cleans up your working directory. This allows you to switch to other branches or work elsewhere. This feature is not currently supported by the GUI, however you can use the GIT command line tools, as show below:

To stash you current work:

git stash save "Feature XYZ"  

Once you stash, you are free to switch branches. When you are ready to resume working on the changes you stashed, you can apply the stash:

git stash apply 

You can stash multiple times. Use git stash list command to see to list of stashes stored on the stash stack.

$ git stash list
stash@{0}: WIP on master: d724198 Feature A
stash@{1}: WIP on master: d724198 Feature B
stash@{2}: WIP on master: c9a03f4 Feature C

git stash apply restores the most recent save, stash@{0} in this case. To restore one of the older stashes, specify its name e.g. git stash apply stash@{2}.

A stash could be applied to any branch not just the same branch it was saved from.

Note: Stash will ignore ‘un-tracked’ files. If you added a new file, you must first add it to the index using git add before stashing.

Diff

The diff view can be used to show differences being applied, it will look something like this:

1563741748614

To make clear what is actually compared, a diff output always starts by declaring which files are are being compared, in this case Local and Server. Further down in the output, the actual changes will be marked as coming from Local or Server. In order to tell them apart, Local and Server are each assigned a symbol: for Local version, this is a minus ("-") sign and for the Server version, a plus ("+") sign is used.

Chunk

A diff doesn't show the complete file from beginning to end: you wouldn't want to see everything in a 10,000 lines file, when only 2 lines have changed. Instead, it only shows those portions that were actually modified. Such a portion is called a "chunk" (or "hunk"). In addition to the actual changed lines, a chunk also contains a bit of "context": some (unchanged) lines before and after the modification so you can better understand in what context that change happened.

Chunk Header

Each of these chunks is prepended by a header. Enclosed in two "@" signs each, Git tells you which lines were affected. In our case the following lines are represented in the second chunk:

  • From the Local file (represented by a "-"), 6 lines are extracted, beginning from line no. 96
  • From file Server file (represented by a "+"), 8 lines are displayed, also starting from line no. 96

Changes

Each changed line is prepended with either a "+" or a "-" symbol. As explained, these symbols help you understand how exactly version local and server look: a line that is prepended with a "-" sign comes from local, while a line with a "+" sign comes from server. In most cases, DATASTAR diffs the files in such a way that you can think of "-" (minus) as "old" content and "+" (plus) as "new" content - although this is not always the case as there could be new server content.

Branches

It is easy to switch branches using the branch menu which will show the local branches, you can checkout other branches from the remote repository using the "Checkout" option.

1564263284973

If you click on the "Branches" button rather than using the drop down, then a branch dialog window will be displayed, this allows you to create a new branch or merge a branch.

1564263558801