Version Control

It is recommended strongly that you use version control software to keep track of your projects. They are free or inexpensive (depending on options chosen), easy to set up and use---particularly through an IDE like Android Studio---and contribute greatly to programming efficiency. Android Studio supports several version control systems: GitHub, Git, Subversion (SVN), CVS, Google Cloud, and Mercurial. All projects developed here are under version control and publicly available from the GitHub repository. The basics of using Git and the GitHub repository with Android Studio are described in this Appendix.

One-Time Setup

Several one-time setup steps are required.

1. Get an Account: First, you will need an account with GitHub. If you do not have one, set one up at https://github.com/join . (The account is free for a public repository option. All projects in this course are stored in public repositories. If you are going to be doing proprietary work that you don't want others to be able to view, a private repository costs $7/month for individuals.) Associated with your account will be an email address, a unique username that you pick, and a password.


2. Check that Git is Properly Configured: in Android Studio with a project open select File > Settings > Version Control > Git and click the Test button in the resulting window. If the system fails the test your system may not have an appropriate version of Git installed; see https://git-scm.com/ for help.


3. Check that Git is properly configured to connect to your GitHub account. From a shell window, issue the following two commands
   
   

      [guidry@M81n ~]$ git config --global user.name
       username
      [guidry@M81n ~]$ git config --global user.email
       emailAddress
   

   If the username and emailAddress output from the above commands don't match the username and email address associated with your GitHub account, set them to the correct values with the following commands:
   
   

      [guidry@M81n ~]$ git config --global user.name "correct username"
      [guidry@M81n ~]$ git config --global user.email "correct email address"
   

   (The --global flag means that this username and email address will be associated with all your projects on this machine.)

Now you are ready to implement systematic version control for projects.

Committing a Project to Version Control

An Android Studio project not yet under version control may be added to Git version control by the following steps.

1. Enable Version Control Integration for the Project: In AS, with a project open that is not presently under version control, from the top menu select VCS > Enable Version Control Integration. In the resulting popup window select Git as the version control system and click OK. New options should appear under the VCS menu and various filenames in the left Project Explorer panel will turn reddish-brown, indicating that they are not yet under version control.


2. Exclude Files from Version Control: Many files do not need to be under version control (in particular, those that are regenerated with each build). Be sure that there is a plain text file called .gitignore in the main directory of the project that lists files to be excluded from version control (it is a "dot" file, so you need to enable display of "hidden files"). Android Studio generates this file automatically for my installation when a new project is created, but it may be missing if the project was imported into Android Studio from another source like Eclipse. A standard list of files to be omitted is
   
   
   • *.iml
   • .gradle
   • /local.properties
   • /.idea/workspace.xml
   • /.idea/libraries
   • .DS_Store
   • /build
   • /captures
   
   
3. With the project to be committed open in AS, select VCS > Import into Version Control > Share Project on GitHub.


4. In the resulting popup window, log into your GitHub account if required and in the resulting popup window give the repo a name (ignore the rest) and click Share. This should give a popup window with a list of files to be committed in reddish-brown. Add an appropriate Commit Message and click OK, which should create the GitHub repository.

The repositories stored under your GitHub account may be viewed and managed on the Web by logging into your account at https://github.com/. If they are designated public (the only option if you have a free account), anyone can view and download the project, but only you and any collaborators that you designate can edit or modify projects.

Checking Out a GitHub Project

A project committed previously to GitHub may be checked out in the following way.

1. From the homescreen of Android Studio select Check out Project from Version Control and select GitHub from the dropdown list.


2. Login to GitHub if required.


3. In the resulting Clone Repository window fill out the information about what Git repository to clone, the parent local directory, and the local directory name for the project and click Clone.


4. This should clone the repository project to the local machine. Note: You may get an error popup about missing files (for example, .iml files). They are missing because they were excluded when the repository was created by the contents of the .gitignore file. Ignore this by choosing Remove Selected for the popup.

You now should be able to compile and execute the project just checked out.

Committing Changes to a Project

When you make changes to the files in a project, you will want to commit them to the GitHub repository. (Note: As new files are added to a project under version control you will be asked if you want to add it to version control; usually your answer should be Yes.)

1. Commit the Changes: On the project bar near the top left right-click on the project name and select Git > Commit Directory. On the resulting Commit Changes popup fill in a Commit Changes message and click Commit (Note: Be descriptive with the message, since this will help if you need to revert to an earlier version of the project at a later date---see the section on this capability below). You should get a popup indicating the number of files changed and the Commit Changes message.


2. Push Changes to GitHub: Right-click on the project name in the project bar and select Git > Repository > Push (or click the up green arrow on the toolbar). On the resulting popup screen select Push. You should get a popup indicating that the push was successful.

The repository project should now be synchronized with the local project. Notice that this is a two-step process: first the revisions are committed locally to version control, and then the results are pushed to the remote GitHub repository. If you wish, these can be combined by choosing Commit and Push from the dropdown menu that appears if you hover over the Commit button down in Step 1 above.

Adding and Removing Individual Files

As you add new files to a project under version control you will typically be prompted whether to place them under version control. Alternatively, a file not under version control can be added manually to version control at any time by right-clicking on its name and selecting File > Git > Add. To remove a file locally, right-click on the name and select File > Delete. However, the deleted file still exists in the repository until the deletion is committed to the repository. (A deleted file is placed on the active changelist, and is displayed in grey font.)

Updating a Local Project from the Repository

If you work on the same project on more than one machine, you will want to be certain that your starting working copy is equivalent to the repository version. To update a local project from the repository, right-click on the project name in the project bar and select Git>Repository>Pull (or click the down green arrow on the toolbar).

Reverting to an Earlier Version

Perhaps the central feature of a version control system is that it permits a project to be rolled back to any previous commit of that project. This is invaluable when you discover that something that worked before in your app is no longer working, and it is not clear what change broke it and when it was made. (C'mon, admit it, you've been there!) Then you can revert to the latest earlier version of the project that you know did work correctly (this is where being clear and descriptive with the message attached to each commit can be very important), and work forward from there to discover where the error was introduced. To roll a file back to an earlier revision,

1. Right-click on the filename in the project panel and select from the popup context menu Local History > Show History. This will open a new window with the revision history of the file in the left panel and a comparison of the current version of the file in your IDE and the version selected by clicking on the revision versions listed in the left panel (which opens as a read-only file), with differences marked.


2. Right-click on the revision that you wish to replace the current version, and select Revert.

This causes the current content of the file to be replaced with the copy of the older-version content. If you wish to keep this change, you must then do a commit and push (as described above) to bring the repository up to date.

It is also sometimes useful to simply start over on edits of a file that have not yet been committed under the version control system (delete local changes). To roll the content of a file back to what it was at the last successful update, check out, or commit: With the file open in the editor select VCS > Local History > Show History. The resulting window shows in the left panel versions not committed and a comparison of the file selected in the left panel and the last commit. Select one or more items in the left panel, right-click, and select Revert from the popup context menu.

Removing a Project from Version Control

To remove a project from version control in Android Studio, open the project and select File > Settings > Version Control. Select the project in the resulting window, click the "-" (minus) button, and click OK. You may also need to remove a preferences file (for example, if you intend to change the name of the project and put it under version control under another name). For my implementation of Git and GitHub this preferences file is at <studio files directory>/<AppName>/.git. For other version control systems there will probably be a similar file. Removing this file forces the creation of a new one if the project is put back under version control. If you don't do this and you change the name of the project and put it under version control with the new name, an attempt to push to GitHub may connect to the original project on GitHub rather than create a new one.

More Advanced GitHub

This Appendix covers only the basics of creating and managing GitHub repositories for Android Studio projects. Much more powerful features such as collaborative editing and forking of repositories into more than one development branch are supported, and GitHub can be used to manage a broad range of resources, not just Android Studio projects (see Project showcases for examples). Further information on using GitHub may be found at GitHub help and GitHub Guides.

Last modified: July 25, 2016