01219245/repository setup
- This is part of 01219245.
In this note, we will setup a hosted Git repository. It will be your 'remote repository. You can also read a section in the Git book for this.
There are a few reasons why you would want to host your Git repository.
- It makes sharing codes easy. (This is the main point for our class, because I have to look over your work in the course.)
- There are additional tools that these Git hosting websites provide, e.g., issue trackers and wikis.
- You have all your development code backed up. So, you don't have to worry that your notebook's hard disk might be broken and you have nothing left.
In this course, you have to host your Git repository (that contains your code and assets) on the web. Here are two main choices for the services:
- GitHub - if you want your repository to be publicly viewable, GitHub is the famous choice.
- BitBucket - also hosts Git repositories. If you want a private repository, BitBucket has a free plan for you if you have no more than 5 collaborators.
Both services also provide GUI applications for maintaining Git repository. While we encourage the usage of Git command line, but if you want to use the GUI version provided by the services, it is OK. Both GitHub and BitBucket provide extensive documentations, you can just follow them instead of this note:
Getting started
Pick the hosting service (GitHub or BitBucket) and create a repository for your project.
If you are using BitBucket, make sure that you create a Git repository, not the Mercurial (hg) one. Also, if you create a private repository in BitBucket, don't forget to add me (jittat@gmail.com) to the project with Read permission. See figure below, for BitBucket:
After that, you will have an empty repository at the server. The next step depends on if you have a local repository for the project. If you have not done anything, you can just clone the repository from the server and start developing. If you have implement some of the game and have local repository, you should start by adding the remote origin and then push your code to the server.
Both GitHub and BitBucket show the instruction for you to get started after creating the repository. (Shown below, github (left), bitbucket (right).)
You can just follow the instructions. Here are another instructions and the explanation of their steps.
- If you have no local Git repository (i.e., you start a new project):
- You should start by creating a new project as if you are starting to work on the tutorial. (Call cocos new and clean up as outlined in Tutorial 100.)
- Create a Git repository by calling git init in your project directory.
- Create .gitignore if you need.
- Add the files.
- Commit the changes, so that you have something to push to the remote repository.
- Now depending on the services (GitHub or BitBucket), you should add the remote origin.
- Both websites would show you the command that begins with git remote add origin follow by the repository URL.
- Run that command to add the remote origin to your local Git repository.
- Then push your first change to the server by calling git push -u origin master
- If you have your local Git repository:
- Change directory to your Git directory.
- Add the remote origin. Follow the instructions the service provides you. The command should start with git remote add origin follow by the repository URL.
- Push your repository with: git push -u origin master
Basic work flows
The work flow for an individual is easy:
- To save recent commits from your local repository to the remote, you push.
- To get commits from the remote repository to your local repository, you pull.
- If you want to start working on the repository on another machine, you clone the repository.
git push
Push: When you want to push your local changes to the remote repository, you call git push. The command takes a few arguments:
git push <repository> <refspec>
The arguments
- repository tells the remote repository you want to push to, and
- refspec tells, essentially, which source branch you want to push, and which destination branch you want to push.
However, some default value has been set. If you leave the repository out, the default is origin. The refspec can also be automatically determined. If you have one branch (e.g., the master branch), the default is to push your master branch to the remote master branch. If you work on a different branch, Git will try to push that branch.
Notes: If you are using Git 2.0, you may see a warning:
warning: push.default is unset; its implicit value is changing in Git 2.0 from 'matching' to 'simple'. [...]
In the previous version of git, the old default behavior (matching) when you do not specify a branch, all local branches matching the remote will be pushed. The new behavior is simple, where Git only pushes your current branch. I suggest that you use the new behavior, and you can set it explicitly to avoid this warning by just call
git config --global push.default simple
to set the global configuration to this new default behavior.
git pull
When you want to pull the changes in the remote to your local repository, you call git pull. In this course, you might not need to do this that often, unless you do your development on many machines.
If you want to start another local repository, you should clone the remote repository once (see next section). Then you call git pull when you want to get the changes.
The syntax for the pull command is roughly the same as the push command. But you have to be careful if you have many branches, Git pull not only gets the changes, but also merges the changes. More precisely, git pull runs the git fetch command and then git merge the changes to your local branch. If you are working on more than one branch, be careful not to fetch and merge a wrong branch into your working branch.
The syntax is:
git pull <repository> <refspec>
You usually call just:
git pull
to fetch all the changes and merge into your local branch.
git clone
When you want to start your local development from a remote repository, you clone the repository.
It can be done by calling
git clone <repository> [<directory>]
in your working directory.
Git clone will create a new directory with the repository. If you do not specify the directory argument, Git will create the directory with the same name as the repository.
When you are cloning from GitHub or BitBucket repositories, the web pages show clearly the URL to the repository that you can clone. You have to choose the protocol for communicating with the server. The typical choices are https or ssh. Using https might be easier in the beginning if you do not want to deal with SSH credentials (or, if you know nothing about it), but using ssh might be nice later on as you might not have to type your password every time you push or pull from the repository. Therefore, I suggest you to start with the https protocol.
Your typical commands should look like (for GitHub)
git clone https://github.com/username/repository-name.git
or (for BitBucket)
git clone https://username@bitbucket.org/username/repository-name.git
