Skip to content
Ilmari Karonen edited this page Dec 23, 2013 · 3 revisions

How does this Git thing work?

The idea behind having a GitHub repository is to make tracking the changing raws easier, and to have a single place where the entire history of the project can be found. You don't have to use Git to contribute, although you might want to give it a try — it's very useful once you get the hang of it.

Here's how the GitHub repo is supposed to work:

  • There's one main development branch ("master"). The person whose turn it is decides what goes on this branch (subject to the rules, of course, i.e. no broken code on the main branch, please). If you don't want to use Git yourself, just send your updates to a repo maintainer (currently Vyznev, but others are welcome to help too).

  • At the end of each turn, a "release branch" is split from the master branch. Only bugfixes go on release branches. The latest release branch is what playtesters should download. For development, you should generally download the latest version from the master branch.

  • If you want to contribute stuff but it's not your turn, send it to a repo maintainer (or just post it in the thread) and ask the person whose turn it is if they'll approve it. If they do, it goes on the main branch; if not, it goes on a new "topic branch" (git jargon) where it can be kept, improved and possibly merged into the main branch later.

    The exception to this are simple bugfixes, which don't require approval and can (and should) be automatically backported to all releases affected by the bug. Contributed code should be based on the current master branch or the latest release, unless it fixes a bug specific to an earlier release. In any case, to make maintaining the repo easier, please try to make it clear which version your submitted changes are based on.

  • If you use Git yourself, you can either fork the repo and submit pull requests for your stuff, or you could ask for direct push access to the main repo (as long as you promise not to mess it up) so you can merge in your own stuff. All "work in progress" should be kept on topic branches, and only tested and working code should be merged into the master branch.

    The nice thing about using Git is that whenever new updates are added to the master branch, you can tell Git to fetch and merge them into your working branch with a few simple commands (or mouse clicks, if you're using a GUI front-end). Assuming there are no conflicts, everything just works. (The one exception is if you've edited the exact same part of some file that has also been changed in the upstream repo, in which case you'll need to resolve the conflict by hand. Then again, you would've had to do the same thing in that case anyway, with or without Git.)

Setting up Git with dfscratch

These instructions are similar to those for players, except that they'll give you a working Git repo / dfscratch install that you can use both for playing dfscratch and for developing it with Git.

Although these instructions try not to assume that you already know how to use Git, they can't possibly substitute for a proper Git tutorial; for that, see e.g. the Pro Git book (available for free online) by Scott Chacon.

  1. Download Dwarf Fortress for your OS.

  2. Clone the dfscratch repo. You can use either a GUI like GitHub for Windows or the following command:

     git clone https://github.com/vyznev/dfscratch.git
    

    If you have a GitHub account (or would like to register one), you might instead prefer to fork the repo on GitHub and then clone your fork. The main advantage of doing this is that it makes sharing your work easier later, since you can push your changes back to your fork on GitHub and use GitHub pull requests to have it merged back into the main repo.

  3. Extract the DF files into the directory containing your repo. Don't worry about overwriting the dfscratch raws; we'll restore them in the next step. Our .gitignore file is set up so that Git ought to ignore the presence of any DF files not belonging to dfscratch.

  4. After unpacking DF over the repo, you need to get rid of the vanilla DF raws and data files. The easiest way to do that is to open the Git command line and run the commands git clean -f and git reset --hard to remove the untracked files and reset any local changes. Once you've done that, run git status, which should say:

     # On branch master
     nothing to commit (working directory clean)
    
  5. Optional: create a new topic branch (e.g. "wip-username", where "username" is your user name) with the command git checkout -b wip-username. You can have as many topic branches as you like, e.g. if you want to work on multiple features at the same time. Use git checkout branch (without the -bswitch) to switch between existing branches.

Using Git

Once you've got the repo set up, you now have a full distributed version control system at your fingertips. Some useful things you can do include:

  • Pull new changes from the main "upstream" repo on GitHub and merge them into yours with git pull.
  • Save a snapshot of your raws with git commit -a (or add individual files with git add and then do a plain git commit).
  • See which files you've changed or added with git status.
  • See what changes you've made since your last commit with git diff. (You can also use this feature to compare your code with older commits, or to see what's changed between two commits or even two branches!)
  • Merge changes from another branch to the current one with git merge. By default this will merge in any changes made to the other branch since the last common ancestor of the two branches, but this can be changed.
  • Apply a single changeset (= commit) from another branch into the current one with git cherry-pick hash, where hash is the random hex string used to identify the commit (or at least the first few hex digits of it).
Clone this wiki locally