Feeds:
Posts
Comments

Archive for the ‘Version Control’ Category

If you have worked with Smart-3D for sometime, you know from experience that, there are bunch of files, which need to be tracked for changes during the lifetime of a project. Obvious ones that come to mind are:  reference data or bulkload files, custom source code files (.vb/.cs/etc.), sql scripts, etc.

Some people use custom in-house software to track changes, some use excel spreadsheets to note this, etc. The gist is – you need some kind of configuration management in place so that any changes made to critical files can be monitored and rolled back if needed. In this article, I’m going to show you a free & robust open-source version control system, Git, that can easily serve typical needs of 3D administrators.

Setup:

To start with, head over to http://git-scm.com/download/win and download the install utility. Run the exe to start the installation process and accept the following prompts:

SNAGHTML2fff93

SNAGHTML30bb34

SNAGHTML31e0ec

Adding, Tracking and Committing Files:

In this workflow, I’m going to be using a simple bulkload file, PipelineProp-Ex.xls, that adds a custom interface, IJUAPipelinePropEx, to CPPipelineSystem. I’ll be using this file to go over typical Git cmd that one would use. The file is something like this:

image

The file resides under D:\SP3D\Test. So to make Git aware of this file, I need to:

A) Create a Git repository in that folder

B) Add the file to the Git repository or more correctly the staging area to begin tracking changes

C) Commit the file when I’m sure about the changes

image

Remember, each time you modify a file, you have to “add” or “stage” the file for Git to “commit” that version of the file. The above 3 steps are what you will use during most Git operations.

Let’s look at these in detail:

  1. Right-Click on the folder and select “Git Bash Here” option. This should open the Git command shell as show below

    image

    image

  2. The shell support typical cmd like ls –l to list files and clear to clear the screenimage
  3. Make current directory a Git repository by using the cmd: git initimage
  4. Let’s look at the status now. So issue a git status
  5. At this stage, Git is telling me that there is a file that is untracked and I need to add it to the staging area so that Git can track it. image
  6. So I’ll add the to the staging area by using the cmd: git add Pipe <TAB> . Use the tab key to fill in rest of the filename. This pushes the file to a “staging” area. So if you change the file now and do a commit, the last changes won’t go thru. since Git requires that you “add” and then commit to get the “last” version. Let’s issue a git status to see what we have:image
  7. I’m going to commit the clean xls file so that I have a point from where to start modifying the file. So I’ll issue the command git commit –m “Initial clean state” and then do a git statusimage
  8. As you can see, Git is telling us that the directory is “clean”. In other words there are no changes to track now.
  9. Let’s fix, our identity issue that Git complained earlier by using the cmds (change to your id & email): git config –global user.name ‘Sunit Joshi’ followed by git config –global user.email sunit.joshi@intergraph.com image
  10. Now let’s go ahead and make changes to the file. The change is simple – we add ‘A’ to each column in CustomInterfaces sheet and then save the file. image
  11. Issue a git status cmd, and sure enough Git will report that there are changes now. Note that it’s asking us to again “add” the file to the staging area and then commit if needed.image
  12. If at this stage, if I’m not sure about the change, I can undo all the changes completely by doing a: git checkout PipelineProp-Ex.xls to rollback. So let’s try it:image
  13. As you can see, the “A”, that I added in the columns is gone. Also make sure to exit Excel, otherwise you will get the message about unable to ‘”Unlink the file”, like I did. At this stage I’ll do a git status again (you can clear the screen using clear cmd) and I have this now: image
  14. Since I rolled back the changes, the file is not in the staging area and also not committed. Remember in git, you need to first add the file to staging area and then commit the changes. You can do this in 2 steps, or just in one using: git commit –a –m ‘Initial clean state” (which adds and commits)
  15. Follow this with a git status cmd and this is what you should see: image
  16. I’ll go ahead and add the “A” back in the columns and save the file. Then I’ll do a git status followed by git commit –a –m “Changed for bulkload” and then again a git status to see the stateimage
  17. I’ll now bulkload this file, which will cause the “A” added to be removed, and a log file created by the bulkload processSNAGHTML7dfee9
  18. A bit later I can see that the bulkload process has finished since the “A” have been removed imageimage
  19. Lets look at what Git says now. So do a git status. Sure enough we see that it reports that the xls file has been modified and also that a new file, .log, has been created.image
  20. So at this stage, I can either commit the file or rollback . Since I’m ok with the change, I’ll commit the file and note the details in my commit message
  21. Since I want to commit only PipelineProp-Ex.xls file, I’ll do it in 2 steps: git add PipelineProp-Ex.xls followed by git commit –m “After bulkload”image
  22. If I wanted to save the log file too, I can do a git add SJ_CatV11.log followed by git commit –m “After bulkload log”.
  23. If I don’t want Git to track the log file, I can create a .gitignore file in the current directory and *.log in it which will cause Git to ignore any .log files.
Checking Out File Versions:

So far we have looked at versioning files, so let’s see how we can checkout a file from a point back in time or in other words from an earlier commit.

Let’s say someone comes along and wants the excel file that we bulkloaded successfully, with all the changes – how do we get him this file? This is where commit history and checkout process comes into picture. Let’s see how we can use these to solve this issue:

  1. First issue a git log to see the commit historySNAGHTML2dcc38b
  2. The one we are interested in, is the one with message “Changed for bulkload”. The entry we need is the commit_id, the value in yellow, which is an SHA1 checksum of the file contents stored in Git repository. You can select the whole entry (though Git needs only first 5 chars) and then do a git checkout commit_idimage
  3. At this stage, it’s best to copy the file to a different folder, say C:\Temp, and then open it there to see if it has the earlier data. If you open it in the same location, you may run into the issue where after you do a git checkout master (next step), Git will say that there are changes that you need to commit or stash (most likely due to Excel). So at this stage you may need to do a git reset –hard and then a git checkout master. If I open the Excel file now, I can see the changes at that point in time – nice & simpleimage
  4. So at this stage, I can go ahead and email this file to the concerned analyst.
  5. If you do a git status now you will see that it reports that we are not in any branch. To see our file in latest state, we need to go back to master branch.image
  6. So just do a git checkout master and then check the file, and it should be version from “last” commit. So always remember to go back to your master branch after a checkout.image

That should be enough to get you started with versioning your files using Git. I would encourage you to checkout the official documentation at Git’s website which goes into more detail and covers other advanced operations.

Read Full Post »