Git is an optional way to keep up-to-date with changes made to the engine. Using git means you don't have to go through the hassle of manually copying in engine changes or downloading a fresh copy of the engine.
Git will also allow you to submit changes to the engine, if you're so inclined to help! (Note that you will need to get a permission from a dev in order to submit your changes, and they will be examined first.) Scroll down to the bottom for some information on how to contribute to the engine development.
Download the git terminal interface: https://git-scm.com/downloads
We recommend not using a client with a GUI (graphical user interface). The reason a lot of people want to use the GUI clients is because people are afraid that they are going to somehow "mess up" with git and break the whole repository permanently. In reality, so long as you commit frequently, it's very, very difficult to actually permanently break something. Git is very good at storing your saved commits and not losing them.
So just use the git terminal interface. It's very simple, despite the fact that you have to type commands. There are only 4 or 5 commands you really need to know, and you can always look them up if you forget.
When you download the terminal interface, it will also come with git GUI, a really buggy and
unfriendly graphical user interface. If you desperately want to use a GUI, use a different program
than this one.
On Windows, when installing, note that the default is to add some options to the right-click
context menu ("Windows Explorer Integration"). I would recommend having
Git Bash Here since it makes it easier to clone directories to the folder you want,
but if it bothers you to have cumbersome additional right-click options,
make sure you uncheck both of these!
Give git your username and email address. These can be absolutely anything you like, and do not have to be your real username or email address. Just so long as they're not blank, git will be happy. However, people will be able to see these, so don't put anything embarrassing here.
git config --global user.name "My Username Here"
git config --global user.email "myemailaddress@example.com"
(Note that git will not give you a confirmation message when you enter these in. You can double-check
that it took by typing git config --global user.name into the terminal.)
Also, we highly recommend changing the default text editor unless you want to wrestle with
vim, a text editor program renown far and wide for its incredibly dense user interface.
On Windows, the following command changes your editor to be notepad:
git config --global core.editor notepad
If you want a different text editor (e.g. notepad++), check out this guide on StackOverflow.
Note: if you ever accidentally open vim, don't panic,
just press the escape key and type :q! and press enter to quit. Obviously.
First navigate to the folder you want to download it to. (Type pwd in the console to make sure you're in the correct directory. If it says /, you will either need to use the cd command (e.g. cd "Documents and Settings") or if you installed the "Windows Explorer Integrations" above, you can right-click on a folder on your computer and open git bash that way. The ls command is also helpful to display the contents of the current folder.)
Once you're in the desired folder, you can then type into the terminal (one command at a time):
git clone https://github.com/MegamixEngine/MegamixEngine
cd MegamixEngine
git remote add engine https://github.com/MegamixEngine/MegamixEngine
Not all of these commands output anything in response. Note that the windows git bash terminal is too good for ctrl+v; you must use shift+insert to paste.
If you later change your mind and want the repository to be located elsewhere, you can cut-paste the whole folder to somewhere else you prefer.
(Just make sure you don't miss the hidden .git subfolder!)
If you are starting a new project, you can skip the next section. If you have existing changes in an existing engine download that you want to keep, proceed to the next section.
If you downloaded the engine without using git, and you've made a lot of changes, then the process becomes a lot harder. It's still possible, however. First, you need to know the version of the engine that downloaded. Then you need to clone the engine as in the header above ("How to download the engine with git").
After the engine is cloned, open the engine directory in git bash and type this:
git tag
Scroll through these until you find the version that you downloaded. It's very important to note exactly which one you downloaded! Next type this:
git reset --hard version-1.x
version-1.x should be replaced with the version tag you want.
Now, in your file browser, delete everything in the cloned repository folder (if you have show-hidden-files enabled, make sure you do not delete the hidden .git folder. If you don't see this folder, don't worry about it.)
Finally, copy the contents of your project into the cloned repository folder and then open git bash again. Type git status to see
a list of files that you have added, removed, or edited, and type git diff to manually inspect what lines have been added.
(Type q to close the diff window.)
At this point, you can commit your changes with git add --all; git commit -m "began using git with project". Finally, you
can pull the latest changes made to the engine since the version you downloaded by typing
git pull origin master
Now this raises the possiblity of a merge conflict, which would be caused by you changing something that was changed in a later version of the engine. Read through the remainder of the guide to learn how to deal with these. It's important that merge conflicts be dealt with correctly, lest you encounter worse problems later on.
After you've edited the files you want to edit, saving changes to a repo is a four-step process: (0) check everything is okay, (1) tell git what files to commit in the next commit, (2) tell git to make a commit, (3) download any changes made since you last downloaded, (4 -- optional) upload the commit to the repository host server. There's a TLDR at the end.
Step Zero: Navigate to the top-level folder in the project and run
git status
It will list all the files that you've edited and also other useful miscellany in a very readable format. This is a good thing to do every time you want to commit, or any time you're confused because something is not working correctly. If there are any unexpected messages at this step, stop and think.
Step One: You have to tell git which files should be commited. If you want to commit everything you've changed (this is usually the case), just type
git add --all
in the top-level folder. Ensure that you have saved everything in GMS before doing this.
Step Two: You have to create the commit.
git commit
This will open up a text editor! It could open up vim if you didn't configure your text editor. If you accidentally open
vim (you'll know because the console will clear and everything will become horrible for you), don't panic, just press
the escape key and type :q! and then enter. Then try changing your editor above.
Step Three: It's now time to download the latest changes. Even if you just want to upload changes, you must still do this before uploading. You should begin by closing GMS, and then type the following:
git pull engine master
This could trigger a merge! If that happens, see the next section.
At this point, if all you wanted was to download the latest changes, you're done. If you would like to upload your changes to a repository online, either to the engine or to your own repository, you may proceed to step 4.
Step Four (Optional): It's finally time to upload your changes.
git push origin master
And you're done!
TL;DR:
git status
git add --all
git commit
git pull engine master
git push engine dev
There are four probable things that could happen when you pull. Either
We'll cover the last two cases.
In this event, git will automatically make a merge commit. It will just open up the text editor (see the above warning about vim!) and it will provide you with a default commit message. There's no reason to change this; just save and close the editor.
If git tells you there are conflicts, first do what you should always do in any uncertain situation:
git status
This will tell you what files need to be fixed. Then just open those files manually in a text editor and search for these things:
<<<<<
These are conflict markers. A typical merge conflict will look like this:
Stuff that was automatically merged, blah blah blah
<<<<<<< MASTER
something your INCONSIDERATE TEAM-MATE did
=======
something YOU did that is much better obviously
>>>>>>> HEAD
More stuff that was automatically merged, blah blah
At the end of the day, you'll need to delete the <<<<<< markers or
your code won't work. However, you should stop and think. If necessary,
consult the team-mate who is caused the conflict that is now making your life miserable.
When you're done fixing up the merge commits (make sure you searched for every <<<<<< marker!), just enter this into the terminal:
git add --all
git commit
This will finalize the merge. Then you can go back to step three of pushing your changes in the previous section.
There are two good ways to avoid merge conflicts:
.gitignore file to your project if there are files you don't want to commit,
like backup files or compiled executables. Look this up on Google.There are two ways to undo changes in git. One way is to reset to a previous commit, the other is to revert a commit, which is a more complicated concept and probably not what you are looking for.
To reset to the most recent commit, just type:
git reset --hard
BE CAREFUL! This actually is not reversible. What you may want to do instead is to commit your changes and then reset to the previous commit:
git add --all;
git commit
git reset HEAD~1
This will make sure you can still access your changes later (they won't be uploaded when you push, though.)
To reset to an even earlier commit, you will need to know the "SHA" of the commit. A SHA is just a
long ID or name for a commit, and it looks something like 8f8ab949 or 8f8ab94901afc39041fa3f447bb752dbb4036799.
Use git log to list all the recent commits (up/down to scroll, q to quit), and when you find the one you want
to reset back to, just type git reset --hard 8f8ab949 (just enter the first few digits of the SHA).
For reference, reverting a commit actually creates a new commmit that undoes the specified commit. This
is useful if you've already uploaded a change. You can look up how to use it; there are some gotchas. (Don't just
type git revert 8f8ab949! Instead type git revert 8f8ab949..HEAD.)
In general: if you want to undo something you've uploaded, use git revert, otherwise use git reset because
it's simpler.
The above guide is for the basics. You'll probably learn a lot more by running into problems and Googling how to solve them. Once you've become a great enough master, you can learn how to use branches and how to "rebase" commits as well.
The main difference between just keeping up-to-date with engine changes and actually contributing to the engine is that you need to push changes, which is described in step 4 above. You first have to fork the engine and switch to the dev branch. Additionally, you will need to send pull requests.
The first thing to do is to fork the engine on GitHub. There should be a button on the GitHub webpage for this.
Once you have a fork, look at the URL -- it should be something like https://github.com/MyUserName/MegamixEngine where "MyUserName" is actually your username. In git, type the following:
git remote set-url origin https://github.com/MegamixEngine/MegamixEngine
Now you should have origin referring to your personal fork, and engine referring to the base repository for the engine.
This is important if you want to contribute to the engine or just to stay up-to-date with unstable, bleeding-edge changes. Type git fetch engine dev and then git checkout dev. When using the instructions for submitting above, instead of typing git push origin master, you should type git push origin dev.
After doing git push origin dev and that goes through, you should go to GitHub and make a pull request, which is a request for us to pull the changes you've made into the engine. Make sure to set the "base" of the PR to be the engine, and the "compare" of the PR to be your own fork. Once a dev with permission has approved it, it will then be in the dev branch, and when the dev branch becomes stable, the engine master branch will merge in the changes from dev and will be released as a new version on the releases page.