CamDawg Posted August 20, 2018 Share Posted August 20, 2018 (edited) 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: 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 September 12, 2021 by CamDawg formatting Quote Link to comment
jastey Posted August 20, 2018 Share Posted August 20, 2018 Good stuff. Thank you! Quote Link to comment
Aquadrizzt Posted August 20, 2018 Share Posted August 20, 2018 Very helpful guide for those who haven't had to deal with version control. Good stuff. Quote Link to comment
CamDawg Posted August 21, 2018 Author Share Posted August 21, 2018 (edited) 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: 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 August 21, 2018 by CamDawg pull request update Quote Link to comment
Mike1072 Posted August 21, 2018 Share Posted August 21, 2018 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 modcheck the mod readme or contact the author to find out Quote Link to comment
AL|EN Posted August 24, 2018 Share Posted August 24, 2018 (edited) 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 August 24, 2018 by ALIENQuake Quote Link to comment
CamDawg Posted August 24, 2018 Author Share Posted August 24, 2018 Alien, you do so much thankless work--if anyone's giving you grief, send 'em my way and I'll set 'em straight. And also, thank you. Quote Link to comment
AL|EN Posted August 27, 2018 Share Posted August 27, 2018 (edited) Well, the first version of "Create New Github Release" is here: https://github.com/InfinityMods/ModRelease Edited June 18, 2019 by AL|EN Quote Link to comment
Luke Posted September 20, 2018 Share Posted September 20, 2018 (edited) 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 September 20, 2018 by Luke Quote Link to comment
AL|EN Posted September 20, 2018 Share Posted September 20, 2018 (edited) 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 September 20, 2018 by ALIENQuake Quote Link to comment
Luke Posted September 20, 2018 Share Posted September 20, 2018 (edited) 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 September 20, 2018 by Luke Quote Link to comment
CamDawg Posted September 20, 2018 Author Share Posted September 20, 2018 .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. Quote Link to comment
Wisp Posted September 26, 2018 Share Posted September 26, 2018 (edited) Something I often see you young whippersnappers trip over is the commit message. The commit message should be readableIt should start with a short, one-line title: 72 characters orless. The title should summarise the commit message. Fewer charactersis good because commands like `revert` add length to the title in theform:> Revert "Title of commit message"Some advocate a title of 50 characters at most. The title should bewritten in the imperative mood, so as to match git itself. The titleshould be capitalised but not end with a period.After the title, there should be a completely blank line, followed bya longer explanation wrapped around 72 characters. Obviously, if thecommit is adequately explained by the title, you can leavethe commit message as a single line.This style integrates with the rest of git and makes for readablemessages. There are various blogs and such opining on the subject andgiving 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 September 26, 2018 by Wisp Quote Link to comment
DavidW Posted September 27, 2018 Share Posted September 27, 2018 Cam (or anyone): how does one revert a set of pushed changes? (It’s hypothetical, I don’t need to do it right now.) Quote Link to comment
Mike1072 Posted September 27, 2018 Share Posted September 27, 2018 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. Quote Link to comment
Recommended Posts
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.