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.
|Android Studio is built on the JetBrains IntelliJ IDEA platform. The Help for that IDE is generally applicable to the Android Studio IDE. An outline of version control procedures in IntelliJ IDEA may be found in Common Version Control Procedures. This discussion is generic for all version control systems (VCS) supported by the IDE, but will suggest the correct procedures for Git and GitHub specifically.|
Several one-time setup steps are required.
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 username [guidry@M81n ~]$ git config --global user.email emailAddress
(The --global flag means that this username and email address will be associated with all your projects on this machine.)[guidry@M81n ~]$ git config --global user.name "correct username" [guidry@M81n ~]$ git config --global user.email "correct email address"
Now you are ready to implement systematic version control for projects.
An Android Studio project not yet under version control may be added to Git version control by the following steps.
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.
A project committed previously to GitHub may be checked out in the following way.
You now should be able to compile and execute the project just checked out.
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.)
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.
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.)
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).
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,
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.
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.
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