#1 @Daniel - I love it. You are explaining the finer points of how git source control works, as that part is what I think a lot of new users miss. A 1,2,3,n series of step to copy will get someone at least started. However, it is important to have a detailed understanding of what happens when you fetch, merge, rebase, commit, push, fork and branch. Knowing this information will prevent someone from completely breaking their repository and having to start over. Keep it up!

#2

Quote:
...but pushing and pulling are actually ways of synchronising the histories of entirely separate repositories.

This was/is the biggest thing for me coming from svn. Still catch myself sometimes. Altering commits too will be useful for fixing up pull requests.

Great and very useful read. Cheers Daniel.

#3 Oh yes, that's something I forgot to add. It's generally not a good idea to amend commits that are already pushed, though you can usually get away with it in our situation. I added a note to amend slide.

Basically, those "random" strings associated with each commit are the hashed data of the commit itself. So each commit should have a unique random string that depends on the contents of the commit. So when you amend a commit, you change its hash value.

Now, that's not so bad, except any commits after that one depend on knowing its hash value. So if you change that hash value, problems happen. So if you're sure there have been no commits after the one you want to amend (for example, from a collaborator), and that it hasn't been pulled already, then you can --amend your local commit and push with -f.

Is it worth putting that explanation in the slideshow? Anyway, the long and short of it is - messing with history is usually a bad idea :P.

#4 Messing with the history is indeed "bad". More so, "nuking" a push is even worse. I've only ever reverted a push once. It actually happened this past week when I made a major change to all the modules in the "module" folder for the master. I actually wanted to make those changes to the "SandboxRefactor" branch. So I forced a revert to the master to a revision, thus completely erasing all history to the master branch. git is extremely powerful, when given full privileges.

For your guide, I highly recommend aiming toward users who fork the Torque 2D master branch. Instruct them from that aspect. Then, let them know about the "development" branch and let them know about switching branches and pulling from a remote. This SCM is by far superior to SVN or MSC, but that comes with the ability to shoot yourself in the foot.

#5 @Daniel : Awesome work! It never occured to me to use a Presentation! Having slides just makes it way easier to follow for readers!

Since git is one of the main hurdles new users face, I think that this type of doc is extremely important.

As such, like Michael has mentioned, I would definitely make it T2D-centric, as other 'getting started' tutorials are plentiful on the web. My favorite one being : rogerdudler.github.io/git-guide/

#6 Yeah, that makes sense. I might reorganise this as a more focused tutorial. The end goal will be to make a pull-request to one of the GG engines (the cool thing is it'll be applicable to both). Along the way I'll go into detail like I have done already.

EDIT: I might remove some of the command-line syntax and focus on concepts. Seems like a solid bet, especially since we have a lot of GUI users aroung here. (boo, hiss ;))

#7 I spend all day bludgeoning a keyboard, I don't want to spend my hobby time doing it too - not for repository chores anyway.

And if anyone really wants to see what a terrible source control system looks like, go use Borland's StarTeam. It is actually easier to do almost anything from the command line than from their horrible visual tool. The worst experience of my life! I whined about transitioning from svn to git, but now I wish I only had that to whine about....

#8 Richard, you've got to learn to love the keyboard... ;)

#9 "Progress" - not making any. After more than 30 years the damned machines still require manual input. My fingers are getting tired.

#10 Started working on version 2 focused on common tasks you'll perform.

#11 Thanks dB. I just added a link here. It is under Github. Coincidentally I added a Github link about updating a fork to the master branch earlier today. I needed that to get my fork to sync with T3D 3.0.

#12 If anyone needs a decent git client www.sourcetreeapp.com/

This is actually a hell of a lot better than github for windows. If you prefer not using the command line.

#13 I've been thinking about checking into that smally. I've been using SmartGit and it works well for me, but Melv recently recommended SourceTree to me.

#14 I gave it a go and honestly was impressed. It doesn't get rid of the git workflow, which is good.. It won't leave you confused too often when you hear someone talking about a git workflow, because it can deal with it. I actually uninstalled smartgit after working with it. ;) I know some users aren't programmers, so I thought I'd point it out, just in case someone could find it useful.

#15 Hmm, an Atlassian app. Interesting. I've been using BitBucket for my private stuff like Walkabout for a while now. They seem decent.

Also, for anyone who's braving the command-line, don't forget the gitk command.

#16 Check this out:
rogerdudler.github.io/git-guide/
I am working through the tutorial at this link. It seems fairly simple so far. I solved one issue I had about maintaining a local repo that is dependent upon what I checked out from my fork of T3D.

#17 Thanks for the sourcetree link. There's somethin I can actually use at 1-3am after working with svn all day.

#18 Huge thank you for the sourcetree link. Interactive rebase! I can finally clean up the commit message spam that gets generated when pulling updates to my fork, and not always resort to nuking my fork and starting over.

I'll have to give the program a good shakedown, but it sounds like this could be the app to feature in tutorials for using Git with Torque.

#19 Demo: Simon brought up that link earlier, it's a great guide. I added the link to the slideshow. Also added some more diagrams and explanation of branches.

#20 I must have tried and used every git gui i can lay my hands on, fr those interested in git flow, the sourcetree has it built in, this simplifies git a lot IMO, while i dont use all of it, i do use the feature branching part quite a lot in many projects.

I also use giteye, like sourcetree its made by one of the bigger players on the repo scene collabnet, it uses java so if your PC is already infected its worth a try, it also has a lot of tools that simplify many of the tasks.