Version control with git

git is what's called version control software. In a nutshell, it's used to track a complete history of a software's development and facilitate collaboration.

The disassembly uses git for its version control. Advantages of this are:

• We have a complete history of changes made to the disassembly over time.
• There are numerous branches (including hack-base) whose differences from the master branch can be tracked through git.
• Projects based on the disassembly, which have become out-of-date due to updates to the hack-base branch, can be updated through a "git merge" operation. This is somewhat complicated for newcomers to git, but may be necessary for major LynnaLab version changes (ie. from v1.X.Y to v2.X.Y).
• git allows multiple people to work on the same project, though if multiple people modify the same thing, somebody will need to handle the merge conflict manually.

This page will attempt to introduce some basic ways you can use git with a LynnaLab/oracles-disasm based project, but cannot possibly cover everything due to the complexity of the tool.

TODO: Concepts

• Commits
• Staging area
• branches
• pushing/pulling

Interfaces

You can use git through the terminal (with the "git" command) or through one of various GUI interfaces.

Terminal interface

(TODO: Cover initial username/email setup)

To use the terminal with a standard LynnaLab setup on Windows, open an MSYS2 UCRT64 shell, then type cd oracles-disasm. This will set your working directory to the oracles-disasm folder, where you can then run git commands.

Essential commands are:

• git status: Check the status of your repository, see if any files are untracked (unknown to git), modified since the last commit, or "staged" (ready to be committed).
• git add: Add files (which were either modified or untracked) to the "staging area" which is what will be committed with a "git commit" operation.
  • git add turns files from red (untracked/modified) to green (staged).
  • Example: git add rooms/ will stage all changes to files in the "rooms/" folder (corresponding to any changes to room layouts made in LynnaLab).
• git commit -m "Commit description here": Create a new commit based on the changes in your staging area.
  • git commit takes all green (staged) files and puts them into the new commit. They will no longer appear when you run git status.
• git log: View a log of all commits. This will include the commits you've made as well as the commits making up the entirety of oracles-disasm.

TODO: GUI interfaces

• gitk is alright
• I don't really use GUI interfaces but I'm sure they're perfectly fine?

Magit

If you're not a programmer you probably have no business using magit but it's actually amazing if you're an Emacs user, only it comes with all the sheer complexity of Emacs itself. -Stewmat

Uploading your repository to github

Suppose you've completed a hack and want to share its source code. The best way to do this is to create a repository on github and push your code to it.

Steps:

Create an SSH keypair

Keypairs are used by github to authenticate you when you attempt to push to a repository. After generating a public/private key pair, you upload the public key to github, and keep the private key safe on your computer. KEEP YOUR PRIVATE KEY SECRET. Anyone who has access to it will have access to your github account along with anything else you use that key for.

The following two steps only need to be performed once.

Generate the keypair

• Run ssh-keygen in a terminal
• It will prompt you for a filename, just press enter to use the default filename (probably id_ed25519)
• Your newly generated keypair should be in the folder C:\msys64\home\<username>\.ssh, the files being id_ed25519 (private key) and id_ed25519.pub (public key).

Add your public key to github

• On Github go to settings -> SSH and GPG keys
• Click on "New SSH Key"
• Set the "Title" to something like "MSYS2 key"
• For the content of the "Key", open C:\msys64\home\<username>\.ssh\id_ed25519.pub, copy its contents, and paste it into the textbox.
• Click "Add SSH Key".

Commit your changes

• Ensure that git status shows a clean repository. There should be no red files (unstaged) or green files (staged). This means that all of the changes you've made have been committed.
  • Use the git add and git commit operations to create a new commit (or commits) until all of your changes have been committed.

Upload the repository to github

• Log into github and create a new repository. (Make sure you create an "empty" repository, not one auto-filled with a readme or anything.)
• In the terminal, create a remote for that repository: git remote add my-remote git@github.com:<Username>/<RepoName>.git
  • Replace <Username> with your github username, and <RepoName> with the name of the repository on github that you just created.
  • Note: Traditionally, origin is used as the remote name, but we are using my-remote as the name here. This is because origin is a remote which already exists and is tracking the main repository, https://github.com/stewmath/oracles-disasm.
• Push your changes: git push -u my-remote
• Note: The first time you do a "push" operation, you may get a warning along the lines that it "can't authenticate the host github.com". It will ask you to proceed, and you can type "y" to proceed.
  • This happens the first time you connect to a new host (github.com) which SSH does not recognize. After you tell it to recognize that host, you won't get this message again unless someone tries to impersonate github.com.
• If all went well, the github repository will now contain your project's git history!
• Next time, to push updates to github, you can simply run git push after making your commits. It will remember to push to my-remote (your github repository).

Other topics

Tags

You can use tags to keep track of version numbers in your source code. Tags reference a specific commit. You'll see the tag numbers on github or when you run git log.

git tag -a v1.4.1 -m "Brief description here"  # Create the tag, named "v1.4.1"
git push my-remote v1.4.1                      # Push the tag to github

Optionally, once you've pushed a tag to github, you can create a release attached to that tag. For ROM hacks, you would attach the .bps file to that release. This is an excellent way to distribute your hack.