Skip to content

How to add a Git Android library project as a sub-module

How to add a Git Android library project as a sub-module

In this article I will be answering the question of “How to add a Git Android library project as a sub-module?” but i don’t really know where to start. I think I’d better start with the time I asked myself “How do I add an android project to another android project?” Where and why such a need came to be?

Everything started last year a few weeks ago. When my recruitment process was going on in Peakup, I bombarded the Peakup Labs department manager Emrah Uslu with a ton of questions like “How many projects are we going to do? What kind of projects are you planning to do? Is there a Native Mobile developer in the team? (This question means “is there a legacy code” and you need to ask it) during the technical interview we had. He said “There are a lot of projects to be done, don’t worry” and added that we were going to do a lot of big and small projects rather than a project that would take years. The idea of “a library that can be used in common between different projects” that came into my mind in my previous job made sense once again. I don’t remember if I mentioned this to him. He especially requested my to create a common library from the first day I started working.

Did you say Java? Of course I know it, Mr Uslu.

For example, the Login and Language settings pages exist in all our projects and they are all the same. Or we will develop tons of methods, customized buttons, a wide arrange of views (CustomView), extension function, web service request architecture and DSL and these need to be in all the projects. As if that were not enough, they are all the same. Instead of going in the copy-paste loop and turning the project into thrash, isn’t it more simple and reasonable to add the common pages and features into a library and use them commonly from there?

I experienced a huge harm of copy-paste before. There for 8-10 projects created by being forked by each other. The smallest change of service meant to make this change in every single one of them one by one. Doesn’t matter what you say, this is not an example of good development. Don’t do it. Stay away from it. You can use the fork feature way more efficiently and do use it.

Open/Closed Principle, Software Reuse Don’t Repeat Yourself. Even when you think about it, you will see that all of the SOLID principles substantially support he library systems, and don’t find copying and pasting codes reasonable.

 Aaand Technically?

I think I’ve talked about what it is and why it is necessary enough. If you have a question like “Alright, got it, but how exactly?” roaming in your mind, please be my guest. When we mentioned libraries, the first thing that came to my mind is JAR files. But I realized that JAR files can only store the ones in Java SDK class. They don’t contain classes like Activity, Fragment, SharedPreferences, WifiManager like in the Android SDK. In the library structure I want, there must be structures like Activity, SharedPreferences. Another structure that comes to our mind in this situation is the AAR files. AAR files have some disadvantages. The biggest one of them is that you need to create an AAR file and add it to your projects every time you add a code. Keeping in mind that there is no legacy code in Peakup, and the library and main applications are created from scratch, together and parallelly; it really is a pain in the neck to deal with the AAR files. Yes, since they would take up a smaller place, AAR files would be my choice if they were created and prepared before in the library, but of course it is not like that.

When we take a look at the requirements:

  • A dynamical structure is in the lead.
  • It is prone to always changing. And it has a structure that wouldn’t cause me (the developer) a lot of work.
  • It had to correspond with the Open/Closed Principle strictly. Because we were going to do a lot of projects and i wasn’t supposed to mess up the existing projects when I added a code to the library in new projects. Any project download from the VSTS has to be in working condition right away.

So here came the Submodule into the play, which is a feature of Git.

The library had to have an Authenticator layer that would be used the same way in each project. You know, the login screen. Since this is the most important job of the library, we named it as PeakAuth. From that day on, I go like “PeakAuth come here, PeakAuth go” and it has kind of become my child. I loved it and until I switched to iOS I always developed it and added something all the time. The first Android App I created in Peakup was EnviSense. And it just got bigger and bigger in time with me saying” Heyy, I would use this extension function in other projects, let me add it to PeakAuth. Heyy, why would I write this date format in each project again and again, let me add it to PeakAuth right away” and adding common features and code snippets. You remember how I compared it to a child? It actually was a child.

Alright dude, got it, just give us the code already for God’s sake.

Note: Since Android Git Submodule is a feature of Git, the library and our main project have to contain git.


How to add a Git Android library project as a sub-module

Before adding the library to our main project, the PeakAuth needs to be a library first. There are 3 steps to achieve this and they are very simple.

    1. A library project in Android cannot have a launcher activity. No activity in the AndroidManifest file can have the Launcher label.
    2. A library project in Android has the label in the app level build on top, not the label.
    3. In the same file of the 2nd item, the applicationId that if normally under default config doesn’t exist in libraries, it needs to be deleted.

That’s it! Now PeakAuth is a library that can be commonly used with the other projects.

So, How Do We Add a Library to Another Android Project?

Now it is time to add the library project we have created to Android projects. If you want, you can write this to the README file in Git so that it is easier for your friends. And also this type of important points shouldn’t be dependent on one developer in the company only. In addition, not just the creater bu the other developers should be able understand easily, add and use when it’s needed. Just like I mentioned a few times, it is clearly explained in the README file how to add the common Android library named PeakAuth that we use in Peakup. I need to mark a very important point in the beginning. You shouldn’t sync till the last step I have written below. The sync will be done after all the connections and settings are made.

    1. Run the project you want to add the library to from the terminal with the cd command. Enter the code shown below and add the link of the library. git submodule add https:… Or in a simpler way, you can add it on SourceTree as well. If you are going to add Git Submodule to your project and especially if it has a dynamic purpose like mine, I definitely recommend you to use SourceTree. The management of a submodule in the project will be way simpler. When you open the project on SourceTree, right-click on the Submodule options as you see in the screenshot below and click on Add Submodule.
    2. Enter the necessary info and link of the submodule into the opened window. If there are multiple branches, you can choose the branch you want to connect to with the Advanced Options. Then, you ofcourse need to click on OK. The name you give to the file you want to add is very important here. We, as Peakup Labs mobile developers, naturally call the file in which the PeakAuth library will exist “peakauth”.

      After this step the .gitmodule file will be added to your main project automatically.
    3. Open the settings.gradle file of the project and add these lines
      :include ':peakauth'
      project(':peakauth').projectDir = new File('peakauth/app')

    4. Add this line as dependency to the application level gradle file of the project
      implementation project(":peakauth")
    5. Sync. Like I said above, you shouldn’t sync until this step.

If you have mistakenly synced in another step, you need to Reset/Discard all the changes on Git, delete all the added files and restart the whole process. Basically go back to the last commit. I did it a few times and couldn’t find a better way than restarting. I also recommend you to commit before starting to add libraries. So that no other changes happen and you don’t lose codes when you reset completely.


If your project looks nested like in the screen shot, it means that the Android Submodule library is ready for use. As you can see, you can navigate in it as you wish. Which is a feature that the AAR libraries don’t have. The icon in the beginning is important too. And in the screenshot below you can see how your project should look on SourceTree.


You can see how it will look when you commit/push PeakAuth i.e. your submodule library, click on the Submodule below your main project on SourceTree in the screenshot below.


Life Saving Note: Update the submodule only in its own repository. If you update the PeakAuth in the EnviSense, it will reflect on the main PeakAuth and it might mess up all the projects that use the library. If you don’t the submodule carefully, you might cause some chaos. As sweet as it is, the management of it will get harder as the project develops.

If you want more information about the Submodule usage in Android, the 2 resources below helped me a lot. I am attaching them here as well.

Click here for the other android related articles on our blog.

Wish you a day fool of kindness, love and reading.