Git Command Line Guide

Not exactly a game guide but I wanted to give this to the poor mappers/spriters and not have this get buried in Discord.

Command line is WAYY more googleable if you have problems and I highly recommend it.

Also be sure to set your name/email in your git client so your commits show properly and are attributed properly

git config --global user.name "Name Here"
git config --global user.email "[email protected]"

As long as the email is added to your GitHub account it will work fine and show your icon on commits. Name can just be your GitHub username or something else, doesn’t matter.

basic git guide:
HEAD: Term for the current location on the “commit tree”, basically your current location in history.
Staging: an in-between state of your local filesystem and a commit. This is so you can have some changes locally but not commit all of them.
Commit: a collection of changes, applied as a “patch” onto the previous (parent) commit. Think of it as a chain link that contains a snapshot of the repository at that time
Branch: A collection of commits in one big chain, that can split off at any time
Merge: Joining two branches
Remote: A secondary git repository to sync changes with, usually GitHub but can be any server that supports the protocol
Upstream: The remote that you are pulling from/pushing to, in that case your fork OR the main beestation repo

git pull remotename branchname runs git fetch remotename and then git merge remotename/branchname
git fetch remotename gets all the new commits from remote
git merge branchname Attempts to merge all new commits from branchname into the current HEAD, through a few strategies that vary:

  • Fast-forward - Simple, used when the new changes are directly on top of, as in, have a continous history rooting from the current HEAD. For example, if someone pushed one commit to origin/master, and your local master didn’t have this one commit, it can simply be “fast forwarded” and add the new commit on the end
  • Recursive: the normal strategy, it tries to put both the local changes AND the remote changes into one branch by adding the commits in what is called a “merge commit”
  • Rebase: this is its own command, git rebase branchname
    This attempts to take all of your LOCAL changes, and then append them to the end of the REMOTE branch, rather than putting the remote branch into your current one. This is personally my favorite for PRs because it makes a clean commit history, but it also “rewrites” all your commits into new ones, so it’s not suitable for branches used by multiple people because it doesn’t maintain the commit tree
    git reset commitsha (or branchname) - Sets the current HEAD to the commit listed OR the branchname listed. If you specify --hard, it will update the local filesystem to match this, if you don’t specify or put --soft, it only updates this in git, keeping your file changes intact

git checkout commitsha (or branchname) - For commits, this will “rewind” you to that commit and also “detaches HEAD”, which basically means you are no longer on a branch and can’t commit stuff. A temporary rewind, essentially. When you check out a branch, it’s basically just moving you to that branch. Do this for new PRs etc.

git branch (branchname) creates a new branch with the current commit history of the branch you are on
git branch -d (branchname) deletes branch with said name

git add (filepath) adds the file to “staging”
git restore --staged (filepath) removes the file from “staging”

git status View what is staged, what is not, also view what branch/commit you are on. VERY useful.
git add . Add ALL local filesystem changes to staging
git checkout -- . Undo all local changes, get rid of them
git checkout HEAD . The same as above but stricter, if it doesn’t work
git checkout HEAD (or --) filepath resets that file to the last commit on your filesystem
git commit -m "Commit message" creates a commit with the current staged changes and adds it to the branch
git push remotename branchname pushes the current local branch to remotename/branchname
git remote add (remotename) (github link) creates a remotename with a github repo so you can push/pull from it
git push -u remotename branchname OR git pull --set-upstream remotename branchname sets the route from your CURRENT local branch to a remote branch. This makes it so you can just type git push or git pull without having to specify the remote or branch.

git reset HEAD~(number) resets current HEAD X commits backwards in the commit history
git checkout HEAD~(number) temporarily rewinds and detaches HEAD X commits back in history

git log show the commit history (q to exit)
git diff HEAD show all the changes you have made locally that are not committed (q to exit)

On merge conflicts:
Look intimidating, aren’t very (unless you don’t know how to code)
When two commits change the same part of the same file, git tries to merge them but can’t since it would probably break the code if it guessed. Instead, it lets you do it yourself.

It writes into the file what looks like this

<<<<<<<<<<<<<<<<<< HEAD
(version before merge)
=================
(new version)
>>>>>>>>>>>>>>>>>> commitsha

It usually does that multiple times per file. Basically compare the two, remove the markers and write the file back how it should be if both were merged into one.

Mapping conflicts:
Run tools/mapmerge2/Resolve Map Conflicts

DMI conflicts:
Run tools/dmi/Resolve Icon Conflicts

Also, perk of using command line, if you want git to AUTO MERGE DMI and DMM, as well as auto-cleanup your maps on commit, just run tools/hooks/Install. No need to run them manually anymore.