Jump to content

A Basic Modder's Guide to Git and Github


Recommended Posts

For a variety of reasons, more and more mods are migrating to Github. There are numerous advantages to doing so, not least of which is that it keeps your mods available even if your host site goes down and also makes it easier for other modders to submit fixes to your mod. However, there's a little bit of a learning curve if you've never used version control, hence this guide. The goal is to cover the most common operations you'll need for creating and maintaining a repository for your mod.

Some Basic Terminology

git is the underlying software that runs the version control for your code. A collection of source code is known as a repository (or repo, for brevity); for example, here's the BG2 Fixpack repo. Within the same repo, you can have multiple branches. Every repo has, at least, a master branch, but you can create others if you're working on a major, long-term revamp or experimental features. A commit is a change that has been submitted to the repo; one of the main advantages of version control is that every commit is tracked (what specifically changed, the author, reasons, etc.). A fork is a copy of the repo; generally these are done so that another author can make their own changes, usually so that they can submit those changes back to the original repo. Moving code between repos are done via a push or pull, depending on which direction the code is traveling--you push code to another repo from yours, or pull code from another repo to yours. A local repo, in terms of this tutorial, is one on your computer whereas a remote repo means the one on Github.

Getting Ready

Create a Github account. Install a local Git client; I've been using (and am quite happy with) TortoiseGit. TortoiseGit allows me to do pretty much any git operation via a right-click, which simplifies the process immensely. Select a local folder to be your repo collections; I personally use an IE mod package folder in my documents folder:

folder.jpg

Those green checks/red exclamation points are from TortoiseGit, providing visual feedback as to whether I have uncommitted changes to my local repos.

Making Your First Repo

On the Github home page is a 'Start New Project' button (or alternatively from your repositories under your account, then New button). It will ask for a name and a description, and then create a shiny new repo for you. Next, go to your local folder you've decided to use for your local repos. Right-click and you will see a 'Git Clone' option in the context menu. It will ask you for a URL; this will be the URL of the Github repo you just created. The directory should be automatically populated once you set a URL, but verify it's correct as well. Press OK and you should get a warning about cloning an empty repo, which is fine.

You now have a local repo--the folder--and a remote repo--the one on Github. Most of your work from this point will simply be keeping them in sync, primarily by pushing files from your local repo on your computer to Github.

Making Your First Commit

Now it's time to get some files into your repo. If this is for an existing mod, simply unpack your mod into the repo folder. If you look at most of the G3 mods on Github, it's simply the mod folder plus a bat file in the base directory. (The bat file is for an internal tool we use to package our mods, which is why you generally won't find copies of WeiDU or .command files in our packages.) Once your files are there, select them all, right-click, and use TortoiseGit > Add from the context menu. You will notice that the dialogue window that comes up has two options--OK and Commit. Selecting OK will simply queue up the files for your next commit, but since we're going to be doing that anyway, just select the Commit button.

Selecting Commit will bring up the Commit dialogue. In this window you'll have a chance to add a message to the commit, which should be a good, easy to understand reason for the change. You'll also see a summary of what's going into the commit (files added/deleted/modified) down below; verify this is correct. Finally, you'll see a 'Commit & Push' button at the bottom, with a down arrow for more options (Commit, ReCommit, and Commit & Push). Now, a commit will make a change to your local repo, e.g. this folder. 'Commit & Push' means that the changes will be made and then pushed to another repo--in this case, your remote Github repo. This is the easiest way to keep your local/remote repos in sync, so try to use this as often as you can. We'll do so now.

You'll see a small bit about the commit, then the Push window will come up. The branches should default to master, and below you can push to Remote or Arbitrary URL. I usually just use the latter (Arbitrary URL) and then you enter your Github repo URL. Click OK, and it should prompt you for your Github username and password, then complete the push. (TortoiseGit can store your username in the settings if you want to cut down on inputs while pushing.) You can now head to your repo on Github and see all of the shiny new files you've added, along with the message you used on the commit.

Maintaining Your Repo

A couple of quirks to be aware of--git is case-sensitive, but Windows is not. This can occasionally bite you when one of your files changes case and your repo thinks it's a new file instead of an existing (but modified) file. One other thing is that file changes in the repo need to be handled by git. For example, if you want to delete a file out of your repo, simply deleting it by pressing delete (or dragging it to the recycle bin) won't update the repo--it will still consider the file to be part of the repo, even though it's not present. Instead, you'll need to right-click the file and use TortoiseGit > Delete. If you want to simply remove the file from the repo but keep it on your computer, use right-click TortoiseGit > Delete (keep local). Files in the repo directory, but not part of the official repo, are known as 'Unversioned files' and will be noted in every commit dialogue; I sometimes keep notes or to-do lists in my repos as unversioned files. Like deletions, renaming files also need to be done through git; right-click and use TortoiseGit > Rename.

Otherwise, the process is pretty straightforward. You can add files (TortoiseGit > Add), or delete or rename (as above). Any files you modify will visually change from a green checkmark to a red exclamation mark; deletions and additions will have a red x or blue plus. When you're ready, simply select the files (or the whole repo) and either commit them, saving the changes locally, or committing and pushing. If you only make local commits, at some point you'll need to TortoiseGit > Push to send them to Github.

This cycle--making changes to your local repo (by modifying/adding/deleting files), committing them, and then pushing them to Github--is the bread and butter of the process, and will likely be the bulk of your work with it.

Making A Release

When you're ready for a release, package your mods up like you would normally and make sure all of your commits have been pushed to Github. Then head to your repo on Github and find the 'X Releases' tab on your repo. You'll see any releases, if they exist, and a "Draft a New Release'. Click it.

Fill in the information--release version, title, description--and then add your mod packages in the box below with the text "Attach binaries by dropping them here or selecting them." Also, be sure to check the "This is a pre-release" if it's a testing release, e.g. an alpha/beta/release candidate. You can them make your release live with 'Publish Release" or save it for later with "Save draft".

Advanced Stuff

All of that will be sufficient for single-author mods; you can stop reading. The true benefits of using something like Github is collaboration--I'll try and cover some simple scenarios you'll encounter.

If you're working on a multi-author project, you may want to consider building a team or, at least, adding the other folks as authors to the repo. Under a repo's settings on Github you'll find "Collaborators & teams" where you can build a team or add individual members. The team construct can be useful for messaging, but given that you likely have a mod forum it will likely be unneeded. Keep in mind that with other authors on a project, you will need to pull their changes (right-click, TortoiseGit > Pull) down to your local repo.

You can also submit changes to another mod even if you're not an author. Any Github repo can be forked (Fork button in the upper right); this will create your own version of the repo. Pull it down to a local repo on your computer, make your changes, commit, and push them back to your repo on Github. You'll notice a 'New pull request' button on your repo page--click it. This will let you verify the changes and to whom you're sending the pull request (it should default to the project you forked from). The author(s) of the other project will get a notification that you've sent them a request and they can merge at their convenience. You may have noticed that I have a copy of Avenger's/Wisp's aTweaks in my repo directory; I made some updates and then sent a pull request to Wisp.

The flipside is that others can fork and send you pull requests for your projects as well. For a simple example, this is the network graph of Tweaks Anthology. You can see three forks from Angel, K4thos, and Isaya, and they've all been merged back into the main branch via pull requests. It's important to note that pull requests are exactly that--if it's a change you don't like for any reason, you can reject it or accept only the parts you want. Remember that, just like in multi-author scenarios, you'll need to pull down the changes in the Github repo down to your local repo.

Edited by CamDawg
formatting
Link to comment

You can also submit changes to another mod even if you're not an author.

For those interested, you can see this process happening right now. I'm working on a new v31 release of SCS, so I created a repo on Github for it. (Technically speaking Alien already had one, and simply transferred ownership to the G3 group.)

 

Mad Mate contacted me with some additional fixes he had, and wanted to give the whole Github thing a shot. Since he's not authorized to change the current repo (he's not an author), he created his own fork of the project. At present, he's made 16 additional commits to his fork of the project:

commits_ahead.jpg

 

If you click the '33 commits' link slightly above that, you can view the entire history of commits on the project, stretching back to the creation of the original repo. You can view the project at any time that of the commits was made (hence the name version control) or see which files were changed in a given commit and how. Let's check out the 'Install fix' commit in a little more detail.

 

First, you can see Mad Mate's entire comment on his commit at the top, crediting Aasim and Alesia_BH, along with links for more info on the problem. This is an excellent example of a good commit comment. Next, the commit screen shows which files were changed which, in this case, is just one file (stratagems/ascension/ssl/finiren.ssl). After that is the diff, which shows the changes in the file--the line in red was removed, the line in green added. The upshot of this commit is that Mad Mate replaced ReallyForceSpell(Myself,WIZARD_MISLEAD) with ReallyForceSpellRES("%WIZARD_MISLEAD_INSTANT%",Myself) at line 82 in stratagems/ascension/ssl/finiren.ssl.

 

When Mad Mate is done with his series of commits, he'll send a pull request to the original repo. Authors/admins on the original repo--e.g. me--will be given the chance to review his changes and then accept or reject them individually.

 

edit: and the pull request has been sent, and accepted.

Edited by CamDawg
pull request update
Link to comment

Just a couple of notes to help clarify permissions questions that you may have as an author or contributor:

  • all mods in the Gibberlings3 organization on GitHub welcome maintenance contributions (e.g. bugfixes, translations, etc.)
  • other types of contributions (e.g. new and changed content) may or may not be welcome, depending on the mod
  • other uses of a mod (e.g. re-use in separate or derived projects) may or may not be welcome, depending on the mod
    • check the mod readme or contact the author to find out
Link to comment

I'm not good at explaining things to people which I already know because everything appears simple for me. But because of this great piece of work, I'm goona try to create a script which will basically:

 

- read VERSION from tp2

- check if there is a release with exactly the same version, skip if it found it

- if not, make a new Git tag, push it and create new Github release

 

Just give me some time, I'm currently busy with 3 projects at once.

Edited by ALIENQuake
Link to comment

Could you explain how to use .gitignore ?

 

I have the following file (named as macOS.gitignore) in the main directory of my project.....

 

 

 

# Created by https://www.gitignore.io/api/macos

 

### macOS ###

# General

.DS_Store

.AppleDouble

.LSOverride

 

# Icon must end with two \r

Icon

# Thumbnails

._*

 

# Files that might appear in the root of a volume

.DocumentRevisions-V100

.fseventsd

.Spotlight-V100

.TemporaryItems

.Trashes

.VolumeIcon.icns

.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share

.AppleDB

.AppleDesktop

Network Trash Folder

Temporary Items

.apdisk

 

# End of https://www.gitignore.io/api/macos

 

 

 

Nonetheless, sometimes files like .DS_Store pop up in the Source Control of my Text Editor (i.e., they're flagged as pending changes......)

Edited by Luke
Link to comment

Could you explain how to use .gitignore ?

 

I have the following file (named as macOS.gitignore) in the main directory of my project.....

Why you renamed the file? It's literally ".gitignore" with a dot at the beginning.

Edited by ALIENQuake
Link to comment

 

Could you explain how to use .gitignore ?

 

I have the following file (named as macOS.gitignore) in the main directory of my project.....

Why you renamed the file? It's literally ".gitignore" with a dot at the beginning.

 

I see, thanks for clarifying -----> reverted it back to ".gitignore".

Edited by Luke
Link to comment

.gitignore does pretty much what it says on the package: tells your repo to ignore files. In some cases, like the one you posted above, it's telling the repo to ignore special, hidden system files. You can also manually add files to the ignore list (right-click > TortoiseGit > Add to ignore list); e.g. perhaps you want to keep a personal to-do list in the folder but not have it be part of the 'official' repo.

Link to comment

Something I often see you young whippersnappers trip over is the commit message.

 

The commit message should be readable

It should start with a short, one-line title: 72 characters or
less. The title should summarise the commit message. Fewer characters
is good because commands like `revert` add length to the title in the
form:

> Revert "Title of commit message"

Some advocate a title of 50 characters at most. The title should be
written in the imperative mood, so as to match git itself. The title
should be capitalised but not end with a period.

After the title, there should be a completely blank line, followed by
a longer explanation wrapped around 72 characters. Obviously, if the
commit is adequately explained by the title, you can leave
the commit message as a single line.

This style integrates with the rest of git and makes for readable
messages. There are various blogs and such opining on the subject and
giving it a more thorough treatment. Take this one, for instance:
https://chris.beams.io/posts/git-commit/

 

TL;DR: short title, blank line, longer explanation, omit the last two if desired.

Edited by Wisp
Link to comment

You can revert a commit using git revert. This has the effect of creating a new commit that undoes all the changes of the old commit.

git revert commitHash

There's a more advanced way to edit and reorganize commits (git rebase) which can rewrite history so that the changes were never committed in the first place, but it's recommended to only use it when you haven't yet pushed your commits somewhere other people can access them.

Link to comment

Join the conversation

You are posting as a guest. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...