“PhoneGap Tutorial 3 Version Control using GIT and BitBucket” is the next in our series of tutorials.
Git is a a version control source code management system, it is a generic technology used by different sites such as github and BitBucket to maintain versions of your code.
This tutorial will not go through all the functionality of git but it will explain the basic functions you will need to store your code in a safe and standard manner.
There are different sites that provide these services as mentioned BitBucket and github are two of them. I am going to relate this tutorial to BitBucket for the simple reason that the free version allows us to create private repositories whereas github only allows publicly visible repositories unless you subscribe to the paid account.
I will relate all functionality relative to our PhoneGap source code, for example there are some directories that we do not need to check in as these are either releated to PhoneGap developer or files that are regenerated on every build that we never change.
You should allow 1 hour to complete this tutorial.
NOTE: The source code for all our tutorials is available on public repositories via BitBucket and Git. The source code for this repository can be downloaded via a git shell or terminal (Linux) using the below command
git clone https://firstname.lastname@example.org/gothailand/git-tutorial.git
You must have followed the installation of Phonegap steps and the “Create our base Application” and “Test our base Application” from the PhoneGap Tutorial 1 (Part 1).
This creates a basic hello world app from the windows PhoneGap developer app and the only other thing it does is move your config.xml file into the ‘www’ directory for ease of build using Adobe PhoneGap build.
The only difference from the steps are you should name your application “Git Tutorial” and give it an ID of “com.gothailand.gittutorial” in Step 3 of “Create our base application”
If you have any issues please leave a comment below.
You will need to ensure that you install git client for windows at https://git-scm.com/download/ this tutorial is not aimed at PhoneGap CLI or Linux but most Linux OS’s are pre-installed with git or you can install it from your relevant software repository.
Finally you will need to create a BitBucket account at https://bitbucket.org/
In this tutorial we will go through
- Create a new public repository using the BitBucket web console and configure
- Create a .gitignore file to ignore directories we do not need to version control for PhoneGap
- Add our “Git Tutorial” app to this repository
Create a new repository using BitBucket
- Firstly log onto BitBucket at https://bitbucket.org/ and select the ‘+’ button
- Then select ‘Create new repository’ below
- Populate the ‘Create a repository’ screen as below
You will need to un-check the Access level to make it a public repository and modify the README drop down to just create a template README file, also make sure that the Git version control system radio button is checked. Then ‘Create repository’
- If you then click on the ‘<> Source’ menu option you should see your only source code in there is the README.md file that is create for you, this file is displayed when viewing the Overview of your project.
- With BitBucket we can also make changes via the Web so lets make a small change to the README.md file, firstly click on the file and select ‘Edit’
- Make a small change to the file and then ‘Commit’
- You will then be presented with an option to name your commit, we will just leave it as default for the moment, also do not create a pull request.
- Once commited you will then be taken to the commit screen with the details of that commit and the file highlighting the changes, you can see a summary of all commits by selecting ‘Commits’ from the left hand side menu which should look like below
If you view your repository ‘Overview’ page you will see the changes we made in ‘README.md’ reflected on the welcome screen. We now have a repository and are ready to add our project “Git Tutorial’ to it
Add PhoneGap project to BitBucket repository
- If you have followed the tutorials correctly you should have a c:\repository directory and also installed git to allow you to create a Git bash shell as below, you need to right click in the folder area of c:\repository and select ‘Git Bash Here’ as below
- From your repository ‘Overview’ screen next to ‘HTTPS’ you will see the path of your respository is something like ‘https://email@example.com/gothailand/git-tutorial.git’ obviously with your own username details in there, this is important as we will use this to clone the project into our local repositoy c:\repository where we have opened the Git Bash shell
- In your Git Bash shell you should be in your c:\repository directory as below
- Next you need to clone the repository you created using the web console to your local machine, you do this my issuing the below command
git clone https://firstname.lastname@example.org/gothailand/git-tutorial.git
This will then clone the repository to your local machine in the c:\repository\git-tutorial
The repository is now cloned and if you change directory to ‘git-tutorial’ and do a ‘dir’ you will see the only file currently is our README.md file. So we need to now add our project files.
- Ensure that your PhoneGap developer windows application is closed down and then drag and drop all files from your ‘Git Tutorial’ directory to the ‘git-tutorial’ directory. Once moved and ‘Git Tutorial’ is empty (apart from the README.md file we did not replace) you can delete the ‘Git Tutorial’ directory, if you need to run PhoneGap developer again you will have to remove the ‘Git Tutorial’ application and add the project from the ‘git-tutorial’ directory.
You will be prompted to overwrite or skip the README.md, skip this as you want to retain the BitBucket version, you can delete this along with the ‘Git Tutorial’ directory.
- Now if we use the below command
We can check the current status of our local repository
We can see that everying is ‘untracked’ by Git meaning the repository is not aware of the files so we need to add them. Firstly there are some directories we do not need to source control so we will create a .gitignore file
- In the c:\repository\git-tutorial directory create a new text file called .gitignore, we need to add the hooks, platforms and plugins directory to this as they are not required in source control as below, if you know how to use ‘vi’ you can easily create using the Git Bash shell, or you can just type
into the shell then edit the file via windows, the file should look like below
- If we do a status now we should see the unrequired directories not being tracked
- Now we can add all our files to the local Git repository using
git add .
You may get a warning about LF characters you can just ignore these, if you do a ‘git status’ now you will see all the new files are added
- It is now time to commit all the new files in preparation for pushing to our remote repository
git commit -m "Push Tutorial Initial check in"
Issuing this commit you will see a lot of ‘create mode’ messages and your changes will be committed locally with the the message above. If you do a git status now you will see below
Because we are operating on the master (i.e. we are not using branching) the status is telling is that our local repository is 1 commit ahead of the remote repository on ‘origin’ (this is the location we cloned our git repository from) so we need to push all our changes back to the remote repository, we do this with the below command
git push origin master
Doing this you should see the below message, and then when doing a status it should tell us our branch is up to date with the remote repository as below
- So the process going forward to keep your repository up to date is:
- Add new files using ‘git add’
- Commit any modified or added files with ‘git commit -m’
- Use ‘git status’ to verify if you need to ‘git push’ or ‘git pull’ files
(‘git pull –all’ will refresh your local repository with any other commits from the web or other users to the BitBucket repository)
This tutorial will not go into great detail about branching and forking etc. but if you are interested in Git there are many posts out there with tutorials and information about git, it is very powerful. You can find a very good Git Bash command reference at https://git-scm.com/docs
If you found this tutorial useful please feel free to comment and share.