FTC #11117 Autonomice

Set-up GitHub Integration with Android Studio on Mac

By Gabriel

Last Updated: 11/1/2019

Note: This document comprises section four of our Android Studio and GitHub Integration guide. Click here to view sections one through three. This tutorial is for the Mac operating system; if you’re using Windows, use this tutorial.  Additionally, if you’ve already followed these steps for another repository in the past, you can skip to step 4. Otherwise, start here:

  1. Configure Android Studio to work with Git
  1. Open Android Studio (if you don’t have it installed, go here and install it).
  2. Go to the settings (command-comma; File → Settings, or, if you don’t have a project open, Configure → Settings).
  3. Go to Version Control → Git (not GitHub).
  4. Verify that there is text in the “Path to Git executable” box. Click “Test.” You computer should already have Git installed, but if the test it doesn’t work or if there is no text in that box, you may need to install Git. (This is readily Google-able.)
  5. Change “Update method” to “Merge” and click “Apply.”
  1. Configure Android Studio to work with your GitHub account
  1. In Android Studio’s settings go to Version Control → GitHub (not Git).
  2. For “Host,” enter “github.com”.
  3. For “Auth Type,” choose “Password.”
  4. For “Login,” enter your GitHub username. For “Password,” enter your GitHub password.
  5. Click “Test.” If it doesn’t work, check your GitHub credentials by trying to log in with them online. Also check your Git path from the last steps.
  6. Click “Apply.” It might ask you to set up a master password; this is optional.
  1. Find the path to the Android SDK
  1. Go to Android Studio’s settings again (see step 3b).
  2. Go to Appearance & Behavior → System Settings → Android SDK
  3. At the top of the window, you should see a box labeled “Android SDK Location.” Select the path in this box and copy it. You will paste it into a file after the next step.
  1. Import the GitHub repository into Android Studio
  1. Open Android Studio. If you have an existing project open in Android Studio, close it (File → Close Project).
  2. Click “Check out project from Version Control” and select “GitHub.”
  3. For “Git Repository URL,” use the drop-down menu to select your team’s repository. If you can’t find it:
  1. Go to your team’s repository’s GitHub page online (if you have access to that repository, it should probably be under “Repositories you contribute to” on the GitHub homepage when you are signed in).
  2. On the GitHub page, click “Clone or download,” and copy the URL that it gives you into “Git Repository URL.” The URL should end in “.git” and should clearly refer to the repository you want to import.
  1. For “Parent Directory” enter wherever you want the files to be stored on your computer. The default is fine; otherwise you can browse with the “…” button.
  2. The “Directory Name” box should be filled in with the repository name. If not, you can find the name on the online repository page, or in the URL you copied.
  3. Click “Clone.” Android Studio will begin to download all the code you need from GitHub. This may take a while.
  4. When Android Studio is finished importing it will ask if you would like to open the project. PAUSE HERE! When this dialog box comes up, do not click on anything yet!
  1. Make a preferences file with the Android SDK path in it (on Windows, we would make an environment variable, but it’s harder to make environment variables on a Mac)
  1. Open TextEdit (in the Applications folder) or another text editor. A word processor (like Word) is not optimal.
  2. Make sure the file is plain text. If you’re using TextEdit, choose Format → Make Plain Text.
  3. Type the following exactly as it appears (without the quotes): “sdk.dir=”
  4. Paste in the path from step 3 (with no space before it). The file should be a single line and should read something like “sdk.dir=/Users/Username/Library/Android/sdk”; it is important to get this exactly right.
  5. Save the file as “local.properties” in the folder Android Studio created for the project. This folder is stored in the location you selected in step 4d (by default it’s a folder called “StudioProjects” in your user home folder). The folder’s name is the name of the GitHub repository. Your text editor may try to add “.txt” onto the end of the file name; do not let it. If you’re not sure, you can check whether it added this ending by selecting the file in Finder and selecting File → Get Info; the full filename should be under “Name & Extension.” If it ends with “.txt” delete this ending and press enter/return.
  1. Configure the Android Studio project
  1. Now you can go back to Android Studio. Click “Yes” to opening/creating a Studio project file.
  2. Click through the next screen; a progress bar should appear. Wait for that to finish; it may take a while.
  3. If you get an error about not being able to find the SDK, make sure you did steps 3 and 5 properly. If you browse to the location you selected in step 4d (by default it’s a folder called “StudioProjects” in your user home folder) and delete/rename it, you can start over at step 3. If you’re still having trouble, or if you get an error about failing to find a target with a hash string, follow these steps:
  1. Cancel, close Android Studio, and open it again.
  2. Instead of importing a project, click “Open an existing Android Studio project”; browse to the location you selected in step 4d (by default it’s a folder called “StudioProjects” in your user home folder).
  3. Select the folder named identically (or similarly) to your repository, and click OK. This should bring you to the progress bar in step 7b again.
  1. You should now see a large window with a progress bar at the bottom. Let it build, which may take a while; select all three modules to include and click OK.
  1. Deal with strange messages
  1. You will probably see several errors at the bottom of the screen. Click the update or install option for each, one at a time, until these errors go away.
  2. You may see three messages once the project is done building: “Unregistered VCS root detected,” “Frameworks detected,” and “Android Gradle Plugin Update Recommended.” Click “Update “ for the Android Gradle message. This should also make the VCS root message go away; I don’t know why. If you click on the gray background of the window, the frameworks message should go away too. Again, no idea why.
  3. Once you’ve dealt with all the errors and messages, restart Android Studio.
  4. When Android Studio loads again you should see information at the bottom of the screen about the “Gradle build.” This will happen each time you open the project, and it’s best to let it finish before you try to do anything.
  5. If you still see errors or messages, repeat parts a and d until they are all resolved.
  1. Do a test commit and push
  1. After the Gradle build is done, click the “1: Project” button on the left side of the window. This should bring up an area where you can navigate the project and open files. There are several different views you can try; I prefer the “Project” view or the “Android” view. The “FtcRobotController” module contains sample programs that you can try, and internal code that you shouldn’t edit. The “TeamCode” is where you put your team’s code to run it.
  2. Select and open the “org.firstinspires.ftc.teamcode” folder within TeamCode (and within subfolders, depending on which view you’re using). This is where your team’s code goes. If you see a file with “test” in its name and ending with “.txt”, open it (by double-clicking). If not, create one for your team with File → New → File
  3. Write something in the test file so that you will have some changes to commit and push to GitHub.
  4. In the toolbar at the top of the window, click the green up arrow with “VCS” written above it.
  5. In the box for “Commit Message,” write a short message that describes what you have done (something informative like “add to the test file to test version control”).
  6. Hover over the “Commit” button, but instead of clicking it choose “Commit and Push….” Committing only affects the Git repository on your computer; “pushing” synchronizes your local changes with the repository on GitHub’s servers. It is generally helpful to do both at the same time.
  7. If Android Studio finds warnings, click “Commit” anyway. If it finds errors, click “Cancel” or “Review” and go fix the errors.
  8. Click “Push” when that window comes up.
  9. You should see a green box that says “Push successful.”
  10. If you go to the GitHub repository online, navigate to TeamCode/src/main/java/org/firstinspires/ftc/teamcode, and open the test file, you should see the changes you made.
  1. Do a test update
  1. Have someone else make a change and push it to GitHub, so you can test the “update” function.
  2. Click the down arrow next to the commit arrow you clicked before. Choose “Merge” and “Using Stash”
  3. This should give you a green box saying either what files have been updated or that “all files are up-to-date,” which means that you were already synchronized.

That’s it! Continue to use the commit and update buttons frequently and your team will never again have to worry about which version of code someone has.