Git for designers
Contents
Setting Up Your Computer to Flash (for Mac users)
1. Install (or update) XCode from the Mac App Store.
2. Install command-line tools for XCode. Open XCode and it will ask you if you want to install command-line tools. Say yes.
3. Install the Android SDK. It may ask you to update the Java SDK or Java for Mac OS. Follow the instructions to do that.
4. Install Homebrew. Follow instructions here.
5. Install the Android platform tools. Type this in Terminal in your home directory: brew install android-platform-tools
6. Create a directory somewhere on your computer where you want to keep the distros that you want to flash.
7. In Terminal, cd to that directory.
8. Inside that directory, clone the FxOS repos. Type the following into Terminal (one at a time):
- git clone https://github.com/Mozilla-TWQA/B2G-flash-tool
- git clone https://github.com/mozilla-b2g/gaia
Putting Patches on Your Device
Specifically your Nexus 4 but I’m guessing the first few steps will work for other phones too.
Has a developer given you a patch link and when you click on it you’re taken to github and think “now what??” Read on my friend!
Overview:
- Add “git remote add <keyword> <url>”
- Sync “git fetch <keyword>”
- Download code “git checkout <keyword>/<branch>”
- Flash (nexus 4 camera) "make install-gaia APP=camera”
Here is an example - https://github.com/mozilla-b2g/gaia/pull/17233
The first step is to open terminal (aka command line) and make your way to wherever you’ve been downloading the code. Do this with cd (change directory) and the name of the folder you want to navigate to. ls (not sure what that stands for) will show you the contents of the folder if you can’t remember names.
Find the github username
Looking at the github page, you want to find the username of the person. This could be listed under participants, in the comments section, or listed in the text at the top, or on the commits page.
In this case, our user is hyunacho.
You can go to their github user page and check out more information about that person: https://github.com/hyunacho Here, you’ll also see repositories they are contributing too.
Add the user
If this person is totally new to you, you have to first add them in order to be able to see their branches and get the code.
What if you don’t remember if you’ve added them? Do “git remote” and you will see a list of what has been added in the past. If they are there, awesome move along. If not, you are going to have to add them.
Go to the person’s user page: https://github.com/hyunacho and click on the repository you want to add. Most likely, this is going to be a repository they have rather than something they have contributed to. In our case we want to add gaia: https://github.com/hyunacho/gaia
On this page you should see a URL that may have the word clone around it. This basically means you want to get a copy of the code. For our example, our URL is: https://github.com/hyunacho/gaia.git
The full command is “git remote add <keyword> <url>"
The first bit “git remote add” is going to add this to our list.
The <keyword> bit is the keyword we want to use to refer to this URL so we don’t have to remember the URL or type it out every time. Go with something easy like the person’s username.
The URL is going to be that clone URL that we found on the github page.
So for our example, the full command is going to be “git remote add hyunacho https://github.com/hyunacho/gaia.git”
Now they are added!
Getting the code - syncing
Next we want to grab everything that is in this repository. We aren’t downloading actual code yet, think of it more like grabbing the Table of Contents for a book. We can then use this to actually grab the specific chapter we want without having to get the whole book.
“git fetch” is what we use to both get this the first time and each time to make sure everything is current and up-to-date.
Recalling what our keyword was we can insert that into the command to make sure everything is current.
“git fetch hyunacho” - much easier than typing the whole URL!
We’ve got our Table of Contents (or what it really is, a database of branches)
Getting the code - finding our branch
Now we need to figure out which branch (chapter) we want to download.
The developer may have told you, or you can figure this out on your own via one of two ways.
“git remote show <keyword>” is going to show you that Table of Contents you just obtained. Scanning that may show you what you need to know.
You can also go back to that very first patch page you found and take a look there: https://github.com/mozilla-b2g/gaia/pull/17233. In this case we can see near the top our user’s name and then “bug971090-preview-gallery”. This is the branch we want! And if we were to do “git remote show hyunacho” we would also see this listed in what was returned.
Whew - almost there!
Getting the code - downloading!
Finally getting the actual code.
With our branch name (chapter) in hand, we can now use “git checkout” to download the code.
“git checkout hyunacho/bug971090-preview-gallery”. So we’re saying get this code, from the URL that is referenced by our keyword hyunacho, specifically this branch (chapter).
If you see some crazy, weird warning talking about “HEAD” and “commits” just ignore it. This is basically telling you that if you try to make code changes, you are going to have some issues when checking it back in. We aren’t changing any code, so we don’t really care.
Push it!
This is probably more specific to the Nexus 4 stuff I’m doing, but here it is anyway.
Now that the code is synced and on your computer, you are ready to flash your phone. Make sure the phone is: - plugged into your computer - on - unlocked (you can open apps and use the phone)
Go back to our lovely friend Terminal and type in there "make install-gaia APP=camera”. This is pretty specific to the camera, I’m guessing you could replace “camera” with any app name and it would have the same effect of updating that app.
And hopefully it worked and you are done!! Watch out for copy/paste errors and typos if you run into any issues.
Running Into Issues
Nothing is Updating!
If it seems like you keep going through this process and nothing appears to be updating, make sure the git checkout process isn't failing. If you see something like this after typing your checkout command, keep reading.
tshakespeare-17453:gaia tshakespeare$ git checkout wilsonpage/996766
error: Your local changes to the following files would be overwritten by checkout:
test_apps/music2/js/metadata_scripts.js
Please, commit your changes or stash them before you can switch branches
Aborting
tshakespeare-17453:gaia tshakespeare$
Basically, git is preventing you from overwriting files that should be the same but are different. Kind of like when you drag a file into a folder with the same file name - you get a warning to prevent you from doing something destructive.
Since we aren't making code changes, I'm not actually sure how we get into this predicament, but apparently we do and there are two ways to fix the problem. We can either stash or reset. The big difference between the two is the ability to undo. If you care (or are curious) what the changes are you can do "git diff". If you get stuck because there is a ton of output, you can type q to quit or enter to see more.
Stash lets you put the changes that were made aside and move on with life. The plus is that you aren't doing anything destructive and you can keep your work (assuming you've been making changes). The downside is you now have something to manage because you keep putting more changes there. "git stash"
Reset is the much, much, much more destructive path. You are discarding all modifications forever and ever (unless you have a photo graphic memory). It's akin to using AI for a few hours making updates/changes and then shutting down the program without saving. There is no undo, no backup, you have shredded the file, burnt the scraps, and thrown the ashes out of a plane. That said, if you're confident that you haven't been changing things and just don't care about overwriting (i.e. most likely us designers), then go this route. There's nothing to manage and you are starting with a clean slate. "git reset --hard"
Phone Won't Restart
If you're finding that you can't get your phone to restart, press & hold the power button to shut off the phone. Then press the power button again. If you see it starting to boot then a black screen. Try these steps.
A great first step is to try and reset gaia. make reset-gaia
Returning to the main branch
After testing out a patch, you may want to reset your phone by returning to the main branch.
1. Get the latest build from the Task Cluster
- If you're not familiar with Task Cluster: you'll need to navigate to the right folder. For foxfood, go here and download the private/build/aries.zip.
- If the zip doesn't download, try logging out and back in again.
2. Download and unzip it.
3. Open Terminal and navigate to that folder.
4. Plug the phone into your computer.
5. Inside the folder you just navigated to, type this into Terminal: flash.sh
A lot of code will run in Terminal. When it's done, your phone will restart with the main (non-patch) branch.
