Git is a source code version control supporting contributions from a number of developers. Git tutorial and reference material is available via including a complete online “Pro Git” book.
This post is a record of some helpful advice given by Fred Beckhusen for RuthAndRoth Git “Organization” Members developing the Ruth 2.0 and Roth 2.0 open source avatar meshes.
I’ll try to explain a bit more about git and how to use it with Ruth and Roth.
First, read the very basics at https://rogerdudler.github.io/git-guide/
In our case, Github.com is a publicly available web site running git, along with a lot of custom web-facing stuff. We use it as a master “repo” or repository for all our public changes. You also run git, which mean you have all the same data as in the github. Anyone with a “git clone” has Everything We Have Ever Done. Unlike other source code control systems, all the data in git is distributed to every machine. Git is simple to use, but DEEP, as it was designed by Linus Torvalds, the genius behind Linux.
I am going to use the command line syntax here, as it is universal in terminology. Almost all these commands and workflow is found in the various Gui’s.
Ways to work in git:
‘git init‘ makes a hidden .git folder in any blank folder, which makes that folder into a ‘git’. You can also do a ‘git clone’ to get a premade git put into that folder, like in Ruth and Roth. All gits have a .git folder, which is typically hidden. You now add stuff to your original folder, delete stuff, rename stuff, (Eg. work on it), and then git add ( git -a) those changes to a temporary work area, and git commit (git -m) the work area to you LOCAL .git. This change is tracked in the .git by a hash. A Hash is a long series of alpha-numeric data that is like a check sum of all the digits, or a CRC, that uniquely identifies all those changes.
You can see any changes in Git with ‘gitk’. gitk can also drill down to the changes in any file.
In the git command line, you can see what is happening with ‘git status’. GUI tools do this for you when you refresh the GUI.
Your Ruth copy started with ‘git clone‘, which brings in the entire .git from Github to your local harddrive. There is the data, and also there is the ‘metadata’ in a hidden folder named .git, which is not human readable without tools. There are many git tools – the command line, git desktop, the git gui, gitk, which shows the history of a git, and so on.
I use the git found by right-clicking any empty area in the ruth repo and selecting Git Gui Here
I pretty much only use git on the command line to do a *git pull*.
A ‘git fetch‘ goes to github and fetches the latest changes to your local .git folder. It does not check out those changes to your working area. Useful if you want to see what’s going on without changing anything in your working folder.
A ‘git pull‘ will fetch the changes to the .git, and also check them out into your working folder.
Good habits: If using the command line, do a ‘git status‘ often. I leave my git gui open at all times, and click refresh often, which is the same thing.
Make commits often. As in Very Often. If you save a Blender file, that is a good time to also commit it so you can get back to that specific blender file if need be. Its a good idea to keep several copies of a blender file as it is easy to go back a step. But this is entirely optional in git workflow. You never need more than one copy of a file. Git does not enforce any rules about what you do to your data. If you want to make a Ruth Rev 1,2,3,4,5 and so on, git does not care. It will track them all. If you make a blend, and commit Rev 1, commit Rev 2, commit rev 3, then git will track every one of those too. Even better, it can track any commits you made while making Rev 3, so long as you saved the blender file, and made commit for it.
My advice is make each commit about one thing. As one example, in Dreamgrid, I have one text file that has a list of all changes. I edit the the document and commit it every time I change something major. I also use ‘gitk’ to see what all I have done everywhere, and update the document for any missing things, typos, and such. This final draft gets committed too, and this text file gets published in the code, as well as on social media. I used to try to maintain a web site to match copies of my code. But they were never in sync. Help is always behind the latest code, the code someone is running is always older than what I am working on, and the web site then rarely matches what they are getting. So I now publish the help in my git, and update it constantly, so any rev closely matches the documents. If I need to clean up some comments in my code, I will ONLY clean up comments, then commit that as “cleaned up comments’. Let’s assume I don’t like the names of two functions. I change those names and commit that one change. The nice thing about the git GUI if I forget to make a commit, I can stage just one or more files with the small change I want to commit, then repeat for another change. Granted, none of this applies to Ruth and Roth mesh bodies, but they do have many steps in their creation, so once you get used to git, you can simply name a file “Ruth.blend” and never have to use another file name for her. Any commit is available to you at any time.
The ‘git checkout‘ command will change the entire repository to whatever it was the moment that particular Hash was committed. It branches off my local copy of the data from the .git onto a new path that it will track, a path that I can just drop after examining the old code/blender, or continue on with, and eventually merge back in with the main trunk. This will probably be rare in Ruth and Roth, though.
‘git stash‘ – save all my changes away on a stack. Useful when I have ‘touched’ a file that I do not want to save back to the git, and that local change is preventing me from going a git pull. git stash will save it away. I can get back the change, if I want, or just ignore that stack after doing a git pull. git stash clear will empty the stash.
‘git reset –hard‘ – A command that throws away everything I have done and forces my working copy to be an exact match of the .git. I use this much less often now. Handy for those times you get frustrated with git not accepting changes, and when you do not understand how to untangle it. I just save my blender or code somewhere else. Then do a hard reset, and copy the file back, commit it, and then it will take a git push. Tread with caution here, as there be dragons!