What is GitPrime in nutshell

 Before I forget here is the link :)

GitPrime is essentially autosave for a local Git repository. Actually it can be run against multiple local git repositories. 

Basically it is a script when run saves the state of your local Git repo whether the working directory is "clean" or "dirty".

I created it because I've really enjoyed an IntelliJ feature called Local History. If you screwed something up you could look back, compare files, figure out what you broke and dig yourself quickly out of an otherwise giant hole. This happened a lot more before switching to Git where checkins are more frequent, but still happens.

What GitPrime gives you:

It gives you access to your repo's contents at any point in the past (till Git cleans things up every two weeks by default). It is meant to 'save your assets'.  :)

Everytime GitPrime is run on a dirty working branch it creates a "commit objects" which is like a stash, but not saved on the 'stash stack'.

GitPrime also creates a log file called gitPrime.log which appends the hashes of these "commit objects".  Such an entry looks like this:

a0af37fd4e20297da159d298237b0acd0bd19302 Sun Oct30 22:38:19 MDT2011 branch: (master) – stash object created by git-prime (DIRTY Working Directory)

2233ee41f42ee05f50bb31a04a2b3f6e524664d5 Sun Oct30 22:38:43 MDT2011 branch: (master) – HEAD hash captured by git-prime (CLEAN Working Directory)

760e7e36e4233b3676cae28189d9f58665aedf68 Sun Oct30 22:38:58 MDT2011 branch: (master) – stash object created by git-prime (DIRTY Working Directory)


Using these hashes you can then do something like:

git diff a0af HEAD - which would give you the differences of your current branch HEAD and some previous state

or

git branch branchname a0af - which would create a new branch from your auto-saved repo from hours or days ago. Cool!

To find these entries you can look at the gitPrime.log file in the top level dir. of your repository.

You can also run gitPrime manually. Once it is in your path just type gitPrime.sh and all your work will be instantly saved but your directory will be completely unaffected. 

How GitPrime is different than "git stash":

It does not affect your working directory at all. It also does not affect the git 'stash'. It is meant to be run continuously by a cron job. 

Otherwise it does work like "git stash" and only tracks stuff committed or added to the index. 

The git commands GitPrime uses:

git stash create

This creates a 'commit object' like a stash, then the script writes out the hash to the gitPrime.log with a bit of meta-data. 

But if your working directory is clean then this command gets no hash back. Then the gitPrime.sh script knows you're on a clean branch and it grabs the HEAD hash and writes that out using:

git rev-parse HEAD 

In both cases before it writes to the log it checks to see if that hash (or an equivalent hash obj with no differences) was just written. If so then the script does not write anything to the log - nothing changed.

Are there any downsides? Only a bit of space

The only thing to know is that every time GitPrime is run against a dirty working branch that it uses 8k of storage. This is small but can add up.  If this runs every ten minutes for a day then it will use ~1 Meg of storage.

However if your branch's working directory is 'clean' / 'committed' then no space is used. GitPrime just records the hash of the current HEAD.

Every two weeks by default Git will clean up all these 'dangling' commit objects that are not reachable via any branch. 

So unless you change the default setting then each repo with a dirty working dir would use up about 14 Meg of space (if a cron job runs it every ten minutes).

If you want to recover this space immediately you can run:  git prune   (though git recommends not running this).  You will loose all of those commit objects.  Your branches will not be affected.

If you want to see how much space is being used you can do a "du -kh on your .git" directory, then run the script a few times manually and look at the difference. 

Where the name comes from:

I started out trying to sort of local tracking branch. This didn't really work and sort of gimped the history. I was going to call such a branch a 'prime branch' hence the name Git Prime. Even though I completely switched strategies the name stuck. 

Installation:

  1. download the files into some directory like 'gitPrime'
  2. update the file gitPrimeCron.sh to point at the git repositories you want to enable for 'gitPrime' tracking. This should be obvious but just replace these entries "<another-git-repository-path>"
  3. create your cronjob to run gitPrimeCron.sh     My cronjob runs every ten minutes and looks like this:

*/10 * * * * /bin/sh /Users/brendan/projects/git-prime/gitPrimeCron.sh


4.  (optional) It is a good idea to add the file gitPrime.log to your .gitignore file. 

That's it!  Three steps that should take less than 5 minutes.

Bonus:  If you add 'gitPrime.sh' to your path then you can run it manually anytime. 

Summary:

Link to GitPrime

GitPrime is a script that works like an auto-save on a git repository.  It is efficient just like Git.  And you will barely know its there until you need it - it does not change your working directory or your git history or anything you can see through any 'common' git commands (unless you REALLY dig). 

Hope you find this helpful! Would love to hear comments. 

  • No labels