[Guide] Why you should consider using Git for your projects

Hi gang!

Well, it has finally happened; I’m seriously enjoying myself with Inform 7. Right up to a point where it has managed to climb up into my (dynamic) Windows 7 start menu (recently started list) and it now sitting next to the likes of Minecraft, NetBeans and “some other software” :smiley:

Figured I’d try to contribute something here, so here goes…

Note: Although my guide keeps Inform 7 based projects in mind (and uses those as an example) my guide can actually be applied in general, that’s because you’ll normally be working around in text(-based) datafiles, which is something Git excels at!

[size=150]Why Git?[/size]

Has this ever happened to you?

  • You work on a project and during the development you try out a few options to see if those work. They don’t, and there’s one routine in particular of which you’re convinced that it should, but it doesn’t. Maybe a bug in the interpreter? So you work around it and forget all about it, until that moment one week later when you suddenly learn that a most common mistake is not to close a sentence with a ;. Could that have happened to you as well? If only you could undo one week worth of changes to find out…
  • You have created an Elven forest which is actually working quite nicely. Because you want a little bit more out of it you decide to add an inner sanction where the player can encounter the Elven tribe. Unfortunately this just doesn’t work too well, so you decide to drop the idea. 2 weeks later someone picks up on your project and offers you their help. One idea they have is to add a secluded, maybe secret, area where the player could meet up with an Elven tribe. You tell them that you already tried that idea but that it didn’t work. But when asked what exactly it was that you tried you can’t really answer because it has been a while ago. Then another idea surfaces: how about adding elven bows? But… you already did that yet didn’t get around to telling them yet. Heck, the rate this is going you’ll spend more time explaining ideas and attempts from the past than actually working on the project! If only you could show them a full summary of everything you tried (and don’t want).
  • You have a nicely working adventure and a great idea to expand on it. The only problem is that your changes will be quite heavy, right up to a point where you’ll be rewriting a large part of your project. But no worries: you’re sure that this will work. Unfortunately, 3 days into the changes, nothing works any longer. And the harder you work on fixing things the more eager you become to just drop the idea entirely and go back to what you had before. If only you had made a backup copy…

Recognize yourself in any of these scenarios? Because if you do then I’m convinced that Git can help you out, it may even change the way you work completely. And no: I’m seriously not exaggerating.

[size=150]So what is Git?[/size]

Git is a so called VCS which stands for Version Control System. A VCS is a system which can store any changes you make in a project but instead of merely saving the changes it actually logs and stores them. So the first advantage you get is that you can always look back at any changes which you made in the past. Not just their description(s): you can also check exactly what it is you did, even extract the actual code if you need to. So things which you build (and later removed) 3 months ago could still be retrieved later if you wanted to. And a whole lot more…

So basically Git is a piece of software which can help you manage the changes you make to your project.

[size=150]So how does it work?[/size]

The whole thing evolves around storing your changes. When you set up a new Git repository (=a storage area where Git saves its data) then you can tell Git to add some files to that repository. Once you’ve done that then Git can keep track of any chances made to those files. It will tell you which file(s) got changed, which file(s) got added and/or removed and it will show you exactly everything that changed.

[center][/center]
[center][size=85]Git can show you exactly what changed in your project…[/size][/center]

As such it is important that you also tell Git about every (major) change you make to your project. If you don’t then it obviously can’t save much :wink: Doing this is referred to as commiting your work. You check what changed, you go ahead with the changes and then commit them. In other words: saving the changes. You need to supply a commit message which explains the change, then Git will handle the rest. The changes are logged and you can continue your work.

Split your work into multiple versions with branches

If you have a working project and want to try something new but you don’t want to lose your work then it couldn’t be easier: just create a new branch. Git will continue to keep track of your changes but this time it will save them besides the main program development. So for example:

A-o-o-o - C

* - o - o - B

A is the point where you started working with Git. A o represents a change which you saved to your repository. C stands for the current situation of your project and B… well, that’s an extra branch which we created. So every change we make from here on will be saved within the branch ‘B’. Want to go back to your main project? Easy! Just switch to the master branch (this is called “checking out”) and all the changes you made will be reset back so that your project is fully the same as it was before you began experimenting.

The best part is that this will allow you to basically maintain 2 ‘versions’ of the same program. Even better: once you’re fully happy with your development branch you can then merge both branches together to form the new and improved adventure.

And if it turns out that the idea wasn’t all that great? No problem: you can always undo your changes.

Now, all of this is merely scratching the surface because Git can do a whole lot more. But i fear that if I’d try to address all that then things might become a bit too complex which isn’t what I want. Therefor I’m keeping the whole thing very easy and straight forward.

[size=150]How to set it up[/size]

First you need to download Git for your environment and install it on your computer. Git is actually a commandline program (so it would normally be used without a GUI) but there are GUI front ends available for most operating systems (Windows, Mac OS, Linux, etc.).

Once you set it up simply open a file manager and find your project directory. In my case that would be for Inform7 and I can find those here: C:\Users\Peter\Documents\Inform\Projects.

Right click somewhere with your mouse and you should see an option saying: “Git GUI Here”. Click on that to start Git’s graphical interface while it uses the directory you’re currently in. Then tell it to create a new repository. Don’t worry: even if there are already some files in the directory you picked then this won’t be a problem: Git will never “just” overwrite any of your work. What it does is create a small hidden directory called .git in which it’ll store its data.

The first time you start Git it’ll show a lot of files in the upper left corner: “Unstaged changes”. This is really very simple: there are no files in your repository yet so Git lists all available files so that you can select what you want to track.

Warning though: be sure that you only add actual project files and not (temporary) build files. For example: in an Inform 7 project directory you’ll come across many files in the Build and Index subdirectories. Those files get constantly recreated whenever you build your project, so it makes no sense to include those in your Git repository. In fact, you might want to either create a text file called .gitignore or manually edit .git/info/exclude and then add this:

/Build/
/Index/

This would tell Git to ignore both directories so that you don’t get any temporary data added to your repository.

Next step is to add all the files you do want included. Check which file(s) you need to add in the same window section, click on the first of a list, scroll down and while keeping control pressed click on the last. You should now have a selection of files, press control-t to actually sTage them. This will move those files to the lower left section of the screen (“Staged changes (will commit)”).

Next be sure to type a brief description of what you’re adding.

[center][/center]
[center][size=85]Adding files to your empty repository.[/size][/center]

Once that’s done all you’ll need now from here on are the buttons which I highlighted in the screenshot above. For now click on “commit” and it will add your changes to your repository. So in this case it will actually add the new files. This is also the reason why it makes sense to add files to your ignore list: this will keep the upper left section free from any clutter.

From here it’s easy: just continue your work as normal. Once you made some specific changes to your project which you want to keep just start Git again, optionally click ‘Rescan’ (if it was already running) and it should soon show you all your changed files in the upper left section. Click “stage changed” (to only add files which you actually edited), type a commit message (a description of your work) and click commit.

That’s all there is to it. Want to check what you did in the past? Check the ‘repository’ menu and select “Visualize masters history”. Do you need to get hold of an old file from the past? “Browse masters files” might be all you’re looking for. Just remember that you can get access to everything from your projects past.

[center][/center]
[center][size=85]Here I’m checking up on a local (non-FI) project.[/size][/center]

I’m well aware that this may take some getting used to, basically you’d be using 2 programs together, where one isn’t as straight forward as the other might be. But even so this is a sure way to safeguard all your hard work. Even better: if you want to share your project with others then you can! All it would take is to set up your repository on the GitHub website.

[size=150]For more information[/size]

As I mentioned above I’m seriously only scratching the surface of what you can actually do with Git. Once you get into more advanced topics such as cloning other projects, pushing (“uploading”) your changes to a project back onto a remote server, maybe even hosting a repository of your own (on your own computer, not GitHub), etc… Once you get into all this then you will truly realize just how extensive this whole thing actually is.

So for more information I suggest you check the Git website, in specific check out the extensive documentation section so that you’ll get a good idea of everything else you can do with this.

And there you have it!

I hope this can be of some help for some of you.

I use Fossil instead. (Fossil is also a version control system.)

I think the main stopping point for most authors of IF using things like git or shared repositories in general is that they are authors rather than programmers. Creating IF is programming, sure, but it has more in common with writing a story or creating a painting than it has in common with making a web browser. Most authors don’t want other people trampling around in their gardens and planting raspberry briars where they want tulips.

Version control is nice, but there are a few different ways to handle it. Git is one of those, but I use rsync and tar files. Someone else might use something else entirely.

However, you’re always going to run into walls trying to convince authors (since that’s the primary role creators of IF see themselves as rather than “programmers”) that they should welcome other people in to muck about with their stories. It’s a strange hybrid really, author/programmer, but it’s still mostly author for most creators of IF. And authors do not like to share their godhood over their creations with others. We like to control the details of our little worlds, that’s why we pick up that old god-complex and write.

Git and similar things might be an easier sell for user-created libraries though.

Making your code public is orthogonal to version control. Your Git repository can be the folder of your project that never leaves your disk. Or you can create a private repository on Gitlab (it has free private repos; Github charges for them) so that you have an online backup in case of disaster.

Using version control is immensely helpful even if you’re the single author of a project. And you don’t need to use detailed commits for your changes if you don’t want to. You can instead just commit your daily work, so you get day-accurate commits. This will at least allow you to switch back to any previous day you want, or view all changes you made to the sources any given day.

Eyup. Version control is cool, via git or whatever other methods a person likes. Though I’m not convinced everyone needs the overkill-that-is-git for every project.

I mentioned the “authors not wanting others mucking about” because the original post mentions it, not because I was confused about version control and public code being tied together:

Fossil and gitlab are new to me. This is such a knowledge rich forum.

Thank you.

I use bitbucket and git to preserve all my whole inform 7 projects directory.

I did not look back.

Git works fine with non-programming stuff. It can be used to track changes in OS configuration files, CAD projects, LibreOffice documents, LaTeX documents, and so on. Nothing has to leave the local machine if you don’t want it to.

One important thing to keep in mind though: my intention is not to convince authors of doing anything. It’s merely to demonstrate a way which could help with keeping your files secured. I’m well aware that most are probably authors, which is exactly why I wrote the above. Because I can well imagine that some may have never heard that options like these exist.

In the end I’m really indifferent to what people use or prefer because if there’s one thing which is the most important of all it’s that different people use different solutions. What works for me doesn’t have to work for you, and vice versa :slight_smile:

But yeah, as others have also mentioned: what makes Git unique in this sense is that you don’t need to share anything. Once you created your repository you can just leave things there and continue to use that.

Thanks for your comments (same to everyone else of course!).