.gitignore for PhoneGap/Cordova 3.0 projects - what should I commit?

Question

I just tried to create a new phonegap 3.0 project... Note: I'm new to phonegap. Anyways, I see the project folder contains:

• .cordova
• merges
• platforms
• plugins
• www

And having tried phonegap local run android I see a lot of binary/generated files in platforms/android. This leaves me wondering, what parts of this folder structure should I add to my git repository. Normally, I would consider it extremely poor practice to commit binary files. Hence, I would normally add patterns like bin/, obj/, *.o, *.pyc etc. to .gitignore to avoid polluting my git repository with things that only serves to create merge conflicts.

Surely, www should be added to git, but what about the other parts of the project. To what extend are they products of the source code, and to what extend are they project configuration?

What do you do? Granted I'm new so I barely understand what makes sense here...

Heterochromosome

I don't know about PhoneGap/Cordova but, when in doubt, just commit everything. You can always remove it later when you learn that something was superfluous :) – Sibling

Answer 1

The answer depends on wich platforms you're developing the phongap app, and if you're following the standard directory structure.

If your project directory structure is standard, then you can start from this gitignore and modify it for your needs.

On a rule of thumb you've to exclude all generated files like the bin/ and gen/ directories. If you're developing an Android version of your app you should exclude build files too like *.apk.

All generated files in the android subdirectory should be excluded too:

Android/bin/
Android/gen/
Android/assets/

Fovea

It doesn't matter what platforms you are developing. There is no harm in ignoring things that only apply to platforms that you are not developing on yet. He has implied he is using the standard directory structure. – Airliah

Shameless plug for my Cordova gitignore: gist.github.com/elliot-labs/c92b3e52053906816074170ada511962 – Trotskyism

Answer 2

Expanding on @Jake Moshenko answer:

I like the idea of omitting the platforms directory. In fact, I am am able to exclude both the plugins and platforms directories. A good starting point for the .gitignore:

platforms/
plugins/

The problem with this is that clean copy of the repo must be initialized before you can actually work with it. It may make sense to create an init script such as:

#!/bin/bash
textReset=$(tput sgr0)
textGreen=$(tput setaf 2)
message_info () {
  echo "${textGreen}[my-app]${textReset} $1"
}

message_info "Creating necessary directories..."
mkdir plugins
mkdir platforms

message_info "Adding platforms..."
# If using cordova, change to: cordova platform add android
phonegap build android
phonegap build ios

message_info "Adding plugins..."
# If using cordova, change to: cordova plugin add
phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

A caveat to this approach is that it makes it a little more challenging to customize the platform specific app code/config outside of what's supported by phonegap/cordova (i.e. screen orientation support).

Update: Bash Gist

This gist contains a more complete script for handling a project that does not commit the plugins and platforms directories. It provides a mechanism for copying the icons and splashscreen images from www to the platform directories (for iOS and Android), installing plugins, and handling platform specific files that should be added to version control.

Update: Grunt Gist

Here is another gist which is a Grunt port of the above mentioned bash script. (Thanks to @obie for suggesting grunt).

Yorkist

How would I deal with adding bespoke plugins / native code or making AndroidManifest.xml changes to accommodate plugin development using this approach? Is there somewhere else that AndroidManifest.xml changes can be added? – Purifoy

See the linked gist, specifically here. It overwrites/adds any files from the platform-merges directory. For example, you could commit platform-merges/android/AndroidManifest.xml. This approach works well for simple projects, but it could complicate things in larger projects. – Yorkist

thanks for your help :) I ended up using grunt to do the same thing (with github.com/gruntjs/grunt-contrib-copy) – Purifoy

I hadn't considered using grunt, definitely something I will look into. – Yorkist

You could avoid the step with creating the plugins and platforms folder by adding a .gitkeep file in each one and putting this in your .gitignore: platforms/* !platforms/.gitkeep plugins/* !plugins/.gitkeep – Teresita

@Teresita Good point, but I believe I avoided that to make it easier to clean the project. i.e. rm -rf platforms plugins. – Yorkist

What is the harm / disadvantage of keeping the plugins directory in git? – Regret

I like to keep the source repository as clean as possible. This is, essentially, dependency management for the plugins. – Yorkist

Answer 3

So I just figured this out through trial and error. The platforms directory can be omitted if you are using phonegap local or remote build, as it is generated on the fly. All of the other folders, including the hidden folder .cordova are required.

Coreligionist

Hi, what if I used some third-party jar file or objective-c source file to customize either android or ios build, for example, Parse Notification integration. It definitely need write some java code, then how to manage the git repository? will phonegap local build android overwritten my customized files? – Chinatown

FYI for me, it looks like PhoneGap Build will build without the .cordova folder - why do you say it is required @Jake Moshenko? – Blasto

This suggestion is entirely incorrect. You should not omit the platforms directory because you will eventually need to add in some platform specific code and plugins if you are doing anything nontrivial. You will also often need to manipulate the android manifest and the ios plists. – Chyou

I would say omitting platforms is a good start. If there are dependencies, they should be kept somewhere else, and copied as a build step after adding a platform. – Cosmology

I prefer this answer. I'm excluding only platforms directory – Combatant

Answer 4

I just wanted to leave here my experience with this issue and the approach we finally followed.

In our phonegap project we started to commit all files less the folder /platform using .gitignore file. We thought this way, when the developer cloned the repository the only action remaining to do would be to execute:

phonegap/cordova add platform

But it wasn't. Once the platform was added and we tried to compile, an error appeared and the app didn't install in the device.

Looking the logs, we got some hits that this error was due to plugins. So we decided to reinstall all the plugins we was using in the project and voilá the app run correctly.

So my advice is to save in the repository all the content less the folders platform and plugins. Create and upload to repository a file README with a list of plugins used in the project.

This way, when a developer clone the repository, he/she will have to:

1.- Add the platforms: phonegap/cordova add platform "platform"

2.- Add the plugins: phonegap/cordova plugin add "plugin"

Hope this helps!

Regards.

Idocrase

Answer 5

A lot of this stuff is old and doesn't really apply to the latest version of Apache Cordova. I'm using Apache Cordova 5.1.1 and this .gitignore allows me to still customize with custom icons etc while blocking all the stuff we don't need to version for both Android and IOS. Yes .gradle is used so don't remove it!

www/
.gradle/
build/
.tmp/
.temp/
coverage/
*.log
node_modules/
bower_components/

Boisterous

Why would you include the www/ folder in there? In my application, that's actually were most of the useful stuff from the web application lives. – Rh

@Rh I guess my list can be a template to get someone started. I thought all the hipsters used the www/ folder as a volatile output for their automated build process. My bad! – Boisterous

I exclude www/ because the contents generated by custom build scripts. You don't really want source files in there. – Pleurodynia

Answer 6

While it's somewhat personal preference, I went with this (for an android only project). Removing most, but keeping what's custom

ToonPlane/platforms/android/*
!ToonPlane/platforms/android/AndroidManifest.xml
ToonPlane/plugins/*
!ToonPlane/plugins/android.json
!ToonPlane/plugins/fetch.json

Charlenacharlene