-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Guide to setup git locally
This guide is intended for beginner and intermediate git users on how to set up git locally to make submitting or testing pull requests easily with less clutter and minimizing issues (like having an outdated local copy). It may also have a tip or two for advanced suers.
Git is a terminal tool. Yes UI tools exist, but they can be traps because even using them, it will be important to understand what git is doing under the hood. This guide will only talk about how to use a cli git. It will give you all the commands you need, so no need to be afraid.
Depending on your OS, install or ensure you have already git: git --version
in your terminal. OSX or linux will most likely already have it, but for windows users I suggest grabbing a "Git Bash" rather than using the default Command Prompt.
You will need a Github account. Use Github tutorial on how to set up an "ssh key", this will authenticate you.
You do not want a master
branch in your fork (i.e. your personal copy). You will never commit to it, it is not useful and keeping it constantly up to date is a chore. So lets look at how to get rid of it. Github requires there to be a default branch, but we have no need of it, so lets create a placeholder branch to be your default.
- Go to cata repo and click "fork".
- Click the
Branch: master \/
button and writeplaceholder
in the textbox. - Go to the
Settings
tab, and remove checkboxes forWikis
,Projects
- Then select the
Branches
pane on theSettings
tab and on the dropdown that saysmaster \/
, chooseplaceholder
- Accept the warning
This placeholder branch will grow out of date quickly, but it doesn't matter. Basically never think about it again.
Go to your fork (1.2.3) and copy the ssh address of your repo, something like git@git. Open your bash/terminal and find the folder where you want the code to be and type either:
-
git clone <git address> .
(if you are in your cataclysm folder) -
git clone <git address> cdda
(if you havent made a dedicated folder yet for where to have the game files, it will make thecdda
folder)
You know have the code from your fork locally. It is time to do some cleanup of more things that you won't need. First lets get rid of your master
completely (to avoid any confusion):
-
git push origin :master
(deletes the master branch from your Github fork).
This step is optional, but recommended and something I do because it makes things even more clean and clear. Let's remove all the tags and branches that exist in the original game repo.
-
git push origin --delete $(git tag -l)
(Removes all tags from your Github fork) -
git tag -l | xargs git tag -d
(Removes all tags locally) - Call to
git tag
should no display nothing.
If there is a problem with these scripts that does all in one go, the commands to delete tags manaully is:
git push origin :tag-name
and git tag -d tagname
.
If you do git branch --all
now, you should see that you have one local branch called placeholder
and that your remote have a lot of branches for previous releases and current features that Kevin is working on. These aren't useful for you, so it may be nice to remove them. You want to end up with something like this:
* placeholder
remotes/origin/HEAD -> origin/placeholder
remotes/origin/placeholder
To do this use this command:
-
git branch --no-color -r --list 'origin/*' | grep -v placeholder | sed 's/origin\///' | xargs git push --delete origin
(removes all except placeholder)
If this command throws and error or doesnt produce the result above when you repeat git branch --all
, you can try this alternative more manual way:
-
git push origin -d master 0.A-branch 0.B-branch 0.C-branch 0.D-branch 0.9-branch 0.8-branch gh-pages
(Removes known branchs) -
git branch -r | grep -v placeholder | cut -d/ -f2-
(Lists all the names of branches we dont need) - You can delete the branches manually with
git push origin -d <branch-name>
, for examplegit push origin -d gh-pages
.
So the word "origin" you see all over these commands refers to your copy (the fork). This is where you will upload (push) changes. But to get changes down from the original game repository (which we will call "upstream"), you need to add a second source (called "remote").
To do this, call this command:
-
git remote add upstream -t master --no-tags [email protected]:CleverRaven/Cataclysm-DDA.git
(Adds the upstream remote) -
git fetch upstream
(download any changes in remote) -
git checkout -b master upstream/master
(create a local master branch that tracks the upstream master) -
git branch -d placeholder
(removes the placeholder locally since you need never check it out or worry about it again)
If you do git branch --all
you should now see this:
* master
remotes/origin/HEAD -> origin/placeholder
remotes/origin/placeholder
remotes/upstream/master
So now you are well set up. Your fork is clean and you have a master locally that you can keep up to date with the games main repo:
-
git checkout master
(Makes sure you are "in" the local master, for example after having worked on a feature) -
git pull upstream master
(Downloads changes in the main repo and merges it into your local master).
So you have seen an issue with the "Good First Issue" tag and now you want to make a go at it. Here is what you do:
-
git checkout master
(Makes sure you are "in" the local master, for example after having worked on a feature) -
git pull upstream master
(Downloads changes in the main repo and merges it into your local master). -
git checkout -b <branch-name>
(with<branch-name>
being replaced with something describing your change, short and with letters and-
, for examplegit checkout -b feature-flight
) - Edit files and have fun.
- Compile and test. Look at how to compile for help on that.
-
git add -p
(asks you for each change it discovers in your local files if it should be included) -
git commit -m "<a description of this changeset>"
(Make the commit message describe the issue) -
git push origin <branch-name>
(Pushes your commits to Github, to your fork. replace<branch-name>
of course.)
Now you can go to https://github.com/CleverRaven/Cataclysm-DDA and it should detect your new branch in a yellow notice there and ask you if you want to create a PR. There is also a a "new pullrequest" button on your github fork page.
You will probably get some feedback on your pull request. The first thing to remember is that this is not mindless critisism, this is people helping you out, making sure that your PR will work well and is high quality. They are your ad hoc team! Sometimes you can accept changes they suggest directly in the web interface, but other times you want to go back to your local files. This is no problem, you can make more edits and more commits and push again (last 3 steps above) until your PR is accepted.
After your PR is accepted, you can delete this branch and get ready for more. If you delete the branch using the button on the PR, skip the 3rd step.
git checkout master
git branch -d <branch-name>
git push origin -d <branch-name>
git pull upstream master
Now you are ready to start from the step above where you create your next feature branch.
Back to the Guide for first time contributors