Git: A General Guide

[eezstreet]

Note: this is pretty WIP. If you just want to download code, this is NOT the guide for you!

 

So, you might have seen OpenJK use something called GitHub to store code. You might be wondering, just what exactly is GitHub anyway? How can it benefit me?

 

Well, the answer to that is quite simple. Ever wanted to work on things together and collaborate, rather than just share .zip files? Git is one of the many solutions to this problem and more.

 

GitHub was started as the premier Git hosting site, with its motto being Social Programming. This is fairly true to an extent, and you'll see why.

 

 

Getting Started

 

To start, you'll want a GitHub account and the GitHub App for Windows, Mac, or Linux, depending on your computer. Use the default settings.

 

Next, you'll need a repository (store of code) to clone (copy the code to your hard drive) or fork (create a new repository based on an existing one). I highly recommend a fork over cloning if you're making significant changes i.e. for a mod. For your repository to fork, I suggest using OpenJK (http://github.com/Razish/OpenJK), but you can use forks of that repository, too. So to do this, log into Githib, and click the Fork button on the repository's page. It'll display a little animation while it works.

 

Okay, you're almost ready. All you need to do now is clone your fork to your working copy (code on your hard drive that is not on the repository). Fire up the Github app, and enter your login (if necessary). On the left, you should see your username. Click on it. This contains all of your repositories which are on Github. You should see one which says "<Your username here>/OpenJK". Right click on it, and hit "Clone repository to...". Navigate to where you want your code to be.

 

You now have the code. Congratulations! In the follow-up yo this, I will be writing on how to store changes on your repository, so that others can use it, how to submit changes back to OpenJK on the official repository, and update your code to the latest OpenJK version.

 

TODO: finish me

Edited April 18, 2013 by eezstreet

[Dusty]

Hey Eezstreet. I be havin a few GitHub woes. Honestly I feel like a bit of a dummy but GitHub isn't as intuitive to me as I thought it would be. I'm mainly having trouble updating my fork's code to the latest OpenJK revision smoothly (the part you didn't add in yet). Simply put I seemed to be able to do pull requests in the past no problem but now GitHub is telling me that the main OpenJK code can't be automatically merged with my own, I'm guessing because there are conflicts? However I can't get a clear view of which files and which code are conflicting and how to manually fix the conflicts...

 

Any chance for a wee bit of help? It would be much appreciated I'll try and figure it out on my own in the mean time.

[Raz0r]

Note: This is all from memory, but I believe the commands are correct.

 

Download a merge program called Meld.

Assuming you have a remote called upstream which points to OpenJK (forking on Github should do this, but I can't remember)

Open a git prompt and type:

git fetch upstream
git rebase upstream/master

Assuming there are merge conflicts (i.e. you've modified the same line of code as someone else working on OpenJK) you will have to do a 2-way merge.

Meld will open with 3 views. I can't quite remember which view is what, but it should be fairly obvious. Remember each merge will have rewound history to the point in time each commit happened.

You want to merge your final changes into the middle file, and hit save.

 

It may take you a few tries to get this working, but don't worry if you screw up a merge, you can do a hard-reset of history via:

git reflog # to see which "ref" or "state" to revert to
git reset --hard HEAD@{1}

[eezstreet]

Simpler way (2 steps, assuming Meld is installed correctly):

git pull upstream
git mergetool

Depending on the tool, some conflicts will be resolved automatically but that doesn't mean that they will be resolved correctly! Make sure to review the merge difflog and squash afterwards.

[Dusty]

Alright, thanks very much for the help guys. I'm going to try it out later today then I'll post back.

[Dusty]

Sorry I've been a bit busy, can't believe it's already been 4 days! Hopefully I'll have time today to finally do the merge.

[Dusty]

So I've been working on manually fixing the conflicts which all seemed to be marked "<<<< HEAD (my code) ====== (OpenJK's code) >>>>>> bunchofrandomcharacters". The shell/console only flagged about 6-8 files that couldn't be automatically merged. Strange thing is though, which I'm seeing a lot in the wp_saber.cpp (one of the flagged files), my code and OpenJK's code is usually completely identical or my code is modified but OpenJK's 'update' is just the default code.

 

Odd thing to me is why can't this be merged automatically? If OpenJK never changed anything in a particular line of code and I did, shouldn't my revision have priority? And if two lines of code are identical, why flag it? In the past I'm pretty sure we did pull requests on my OpenJK fork from the main project once or twice and it all merged fine automatically...

 

I'm wondering... did OpenJK update all their code files with a new license or some other cosmetic change, that is causing GitHub and everything else to think that there are code changes when there aren't really any? I.e. the file line count changed, character positions etc. but nothing that affects code functionality?

 

 

EDIT: Maybe I should use Meld to do this via Razor's instructions. So far Meld hasn't pulled up for me using your method Eez. It just told me I had conflicts in those certain files so I'm trying to fix them now in Visual Studio per some guide I found on the internet which might take a lot longer.

 

EDIT No. 2: After searching through my wp_saber.cpp file a bit, I'm estimating there's probably over 100 of these "conflicts". Something's not right.

[eezstreet]

What happens when you do "git mergetool"?

[Raz0r]

Remember,

It may take you a few tries to get this working, but don't worry if you screw up a merge, you can do a hard-reset of history via:

git reflog # to see which "ref" or "state" to revert to
git reset --hard HEAD@{1}

 

[Dusty]

Sorry I've still been having trouble but I'm learning, slowly. 

 

What I've been doing:

instead of using "upstream" which doesn't seem to work, either git can't find it or tells me I don't have access privileges IIRC.

 

First, I've been using a mix of the GitHub website's recommended commands:

 

 

Step 1: From your project repository, check out a new branch and test the changes.

git checkout -b JACoders-master master

 

Step 2: Merge the changes and update on GitHub.

git checkout master
git merge --no-ff JACoders-master
git push origin master

 

 

Walking back through it as I type:

I'll do step 1. And then I can't do the git merge command until I've "fixed" the conflicts generated by the git pull command. The conflicts generated always seem to be the same as the way I described above. Most of the files are merged but the same few that aren't (like wp_saber.cpp) have those strange conflicts in them. When I type git mergetool after this it tries to merge the "problem" files in the powershell/command prompt thingy without opening Meld.

 

The files it tries to fix are these:  

• code/client/client.h
• code/game/AI_Jedi.cpp
• code/game/bg_panimate.cpp
• code/game/bg_pmove.cpp
• code/game/wp_saber.cpp
• code/rd-vanilla/tr_draw.cpp
• code/ui/ui_atoms.cpp
• code/ui/ui_main.cpp
• code/ui/ui_public.h

All the attempted merges fail.

 

Curiously the files seem to mostly be ones that I modified and OpenJK didn't. All the ones in the game/ folder I modified for sure. The last few I'm not sure about, @@redsaurus may have modified them when he set up save game screenshots. The first file client.h is no problem because it only has 1 conflict and it's actually a genuine conflict about the # ifdef JK2_mode code or something like that, as opposed to the 100s of weird conflicts in my files.

 

 

EDIT: Random question. How do I switch what branch I'm working with in the Git shell manually without doing anything else? It tends to switch branches by itself when I do some of the commands.

[Raz0r]

git checkout <branch-name>

[Dusty]

I think part of the problem is I'm a bit confused between Git Shell, Git, and Meld. I didn't set up Meld correctly to be used by the git mergetool command which would probably help. I'm having a bit of trouble though because it seems like all the instruction sets for setting up Meld for use with the mergetool command are for Git and not Git Shell / Windows Power Shell. (Note I may not be using all these terms correctly, I am a complete console / command prompt / dos / windows powershell / non-pretty non-GUI program noob)

 

EDIT: The main trouble I'm having is all the commands I see for setting up Meld seem to be for other Git tools. I'm using the standard "Git Shell" Windows powershell environment but all the commands are for Git bash. Maybe I should try that...

[Raz0r]

They're the same thing. If it's a command-line interface to git, it will work.

[Didz]

You'll need to have the path to your meld.exe in your PATH environment variable.

• Open the System window with Start + Pause/Break
• Go to 'Advanced system settings' then click 'Environment Variables...'
• Select the 'Path' variable under System variables and click 'Edit...'
• At the end of the variable value, add ;C:\Path\To\Your\Meld\Folder (The semicolon is used to separate paths)
• Save all that

 

Now you need to make sure Git is configured to use meld.exe as your 'mergetool'.

• Open Notepad++ ideally, or Wordpad if you don't want to install it. (Don't use plain-old notepad)
• Type this into the file open dialogue: "%userprofile%\.gitconfig" (Literally, including quotes)
• Your user .gitconfig file should now be open. If it doesn't, just create a new file.
• Add meld as the mergetool to this config file like this: http://meldmerge.org/help/resolving-conflicts.html
• Save the file. If it's a new file, use the same path as above when saving the file.

 

Now after pulling, you should get Meld opening when you do git mergetool to resolve your merge conflicts.

[Dusty]

^Thank you much. No way I would have figured that out on my own. I followed your instructions exactly, and now Git Shell is saying " The merge tool meld is not available as 'meld' " when I try to use git mergetool. I feel like Git Shell doesn't know where it's looking for meld...

 

(about a minute after typing the above...)

 

YES. YES. IT WORKED FINALLY.

 

All I had to do was enter these two commands into Git Shell after following your instructions:

git config --global merge.tool meld
git config --global mergetool.meld.path /c/Program files (x86)/Meld/meld/meldc.exe

Now to see if Meld actually helps my predicament a bit... Thank you Didz and everyone (but especially Didz because he broke it down for me like the noob I am )

 

EDIT: Line breaking why you no work? Here's where I found those commands if it's any help to anyone who might be reading this: http://stackoverflow.com/questions/12956509/how-to-set-meld-as-git-mergetool

[Dusty]

Meld is definitely helping, but this merging is still quite a mess. I think I'm realizing where all this mess is coming from though.

 

It is Razor's fault . Your freaking [sP] Fix compiler warnings batch of changes has created thousands of non-changes in every file I have to sort through.

[eezstreet]

If it's whitespace issues, then Meld should nnot be bringing them up?

 

 

(I don't know, I use KDiff, long live GNU)

[Dusty]

So I finally finished. 

 

If it's whitespace issues, then Meld should nnot be bringing them up?


(I don't know, I use KDiff, long live GNU)

 

I swear I'm not crazy, just look here https://github.com/JACoders/OpenJK/commit/5ab07009afb306f2852a97caedf4eaab8774c743 and look at wp_saber.cpp or bg_panimate.cpp and see all the hundreds of "changes" in these files. I don't know if they're whitespace issues or not, it looks to my eyes more like whatever Razor used or did a lot of lines we're deleted and then re-written exactly the same.

 

Also, I have one last problem. I finally finished committing my manual merges to https://github.com/DustysPatch/OpenJK but the way I did it must have been sloppy because it's still showing me as ahead and behind on commits compared to JACoders/master. Is there anyway I can fix or manually override those numbers?

[eezstreet]

If your master contains changes from the origin, then yes, those numbers are intended. You may need to squash down commits.

[Didz]

If it shows that you're behind on JACoders/master still, do another pull, merge the changes in, push back to your origin.

 

I noticed you were using Pull Requests for some reason on your own GitHub repository. You don't need to make use of GitHub's Pull Requests, those are for the community to make requests to you, or if you have any features to merge that you want community participation in discussing.

[Dusty]

So I'm updating my fork of OpenJK with the latest code again to resolve some crashes and to try and fix the commits ahead/behind count, and I'm having some similar issues again. I'm going to deal with each file manually one by one and I should be able to take care of it, however, I just wanted to point something out, and ask if this is normal?

 

Here are the merge conflicts git is saying I have:

CMakeLists.txt: needs merge

CMakeModules/InstallZIP.cmake: needs merge

README.md: needs merge

code/CMakeLists.txt: needs merge

code/client/client.h: needs merge

code/client/snd_dma.cpp: needs merge

code/game/AI_Jedi.cpp: needs merge

code/game/CMakeLists.txt: needs merge

code/game/bg_panimate.cpp: needs merge

code/game/bg_pmove.cpp: needs merge

code/game/wp_saber.cpp: needs merge

code/qcommon/common.cpp: needs merge

code/qcommon/files.cpp: needs merge

code/qcommon/q_shared.h: needs merge

code/qcommon/timing.h: needs merge

code/rd-vanilla/CMakeLists.txt: needs merge

code/rd-vanilla/qgl.h: needs merge

code/ui/ui_atoms.cpp: needs merge

code/ui/ui_main.cpp: needs merge

code/ui/ui_public.h: needs merge

codemp/CMakeLists.txt: needs merge

codemp/cgame/CMakeLists.txt: needs merge

codemp/client/FxScheduler.cpp: needs merge

codemp/client/snd_dma.cpp: needs merge

codemp/game/CMakeLists.txt: needs merge

codemp/qcommon/common.cpp: needs merge

codemp/qcommon/files.cpp: needs merge

codemp/rd-vanilla/CMakeLists.txt: needs merge

codemp/rd-vanilla/qgl.h: needs merge

codemp/rd-vanilla/tr_cmds.cpp: needs merge

codemp/rd-vanilla/tr_image.cpp: needs merge

codemp/rd-vanilla/tr_init.cpp: needs merge

codemp/ui/CMakeLists.txt: needs merge

codemp/ui/ui_main.c: needs merge

shared/sdl/sdl_input.cpp: needs merge

shared/sdl/sdl_window.cpp: needs merge

shared/sys/con_win32.cpp: needs merge

shared/sys/sys_win32.cpp: needs merge

 

Some of these files I have never touched. Why are there merge conflicts that can't be resolved automatically in these files? For example, half of those files are multiplayer code, which I can guarantee I have not tinkered with (my mod is an SP only mod, I don't even include MP code in the solution files).

 

 

EDIT: Perhaps there's some sort of setting I can change, like "overwrite local with remote if no local changes since download" or something...