Note: It may make the most sense NOT to check out these plugins from these repositories to work on them, but to check them out as submodules of the individual apps (kmaps, mms, or places) instead. See the instructions for "Working with an Existing Repository" below.

Importation of a New Project

If you are merging a local project with the Rails apps or adding it as a new app altogether, follow the instructions for Importing a New Rails Project.

If you are starting from scratch and just want to modify existing THL Rails apps, or have already done the import above, see "Getting and Pushing the Code" below.

Getting and Pushing the Code – Working with a Local Repository

1. Getting a local repository. Make sure to use the private URL (git@github.com…) for your development machine to allow you to push your changes back to the GitHub repository. If cloning doesn't work, contact Andres to be added as a collaborator to the repository.

2. Staging and committing changes to the local repository on your development machine. If you are working with plugin (aka submodule) code, see the special "Modifying Plugins" instructions below.

git add .
git commit

3. Pushing changes to remote repository (GitHub):

git push

4. Getting changes from remote repository (GitHub):

git pull origin master

If the changes included the updating a plugin (you would see among the files changed the folder name, for example, vendor/plugins/mms_engine), you need to pull the latest plugin code separately:

git submodule update

Modifying Plugins

It might make the most sense NOT to check out plugins from their individual repositories, but to work with them as submodules of the individual apps (kmaps, mms, or places) instead. If you have cloned any of these apps, you automatically pulled down the plugin code when you did "git submodule update." Just be sure to follow these steps before making any changes.

Getting the proper version of the plugin code

1. Go into the plugin folder, for example:

cd vendor/plugins/mms_engine

2. Check the remote repository URL:

git remote -v

3. If origin is pointing to a read-only URL (i.e. does not start with git@), change it to private URL. If its already pointing to private URL, you should skip this step. Doing this won't change the submodule URL; it will still point to the public URL, but now it will allow you to commit changes directly from your clone repository.

5. If you are not in master, but in "(no branch)", then you should check out master. If you are in master, you should skip this step. This has to be done before you make your changes or you'll lose them.

git checkout master

Applying your plugin code changes

1. Push plugin code back to the remote repository. While in the plugin directory (e.g. vendor/plugins/mms_engine), do the following:

git add .
git commit
git push

2. Push the plugin changes for the whole app project itself:

cd ../../..
git add .
git commit
git push

3. Update the app project with all the latest code:

git pull
git submodule update

Applying your plugin changes to other projects that use the same plugin:

1. Check out the project and go to the plugin folder. For example:

cd vendor/plugins/mms_engine

2. Confirm what branch you are in:

git branch

3. If you are not in master, but in (no branch), then you should check out master. If you are in master, you should skip this step. This has to be done before you make your changes or you'll lose them.

git checkout master

4. Pull changes:

git pull origin master

If that doesn't work, try merging the changes:

git merge origin/master

5. Push the reference to the latest release for that plugin/submodule:

cd ../../..
git add .
git commit
git push

6. Update all changes:

git pull
git submodule update

Managing Branches

Creation

To create a branch locally:

git branch stable

To push the newly created branch to the remote repository:

git push origin stable

Tracking a Specific Branch in the Server

To associate a remote branch to a local branch, check out such branch, and make it the default (this is how the server is setup originally) run:

git checkout --track origin/stable

If a "fatal: git checkout: updating paths is incompatible with switching branches" error message is returned, it's likely that the local repo isn't aware of the branch yet. Try:

git remote show origin

If the remote branch you want is listed under "New remote branches", then it needs to be fetched:

git fetch

After this, running git pull fetches and merges from origin/stable (which is what we want) instead of origin/master.

git pull

Merging Changes in master to a branch

The lastest code will be kept on master (what was trunk in svn). Because of this, in the local repository of a developer, they will usually be pointing to master. So first switch to the branch:

git checkout stable

Merge changes already committed changes from master. This merge also commits (if there weren't any conflicts). The conflicting files you have to add and commit manually.

git merge master

Not necessary, but you can switch back to master to not forget later.

git checkout master

Now push changes to remote repository. This will push all changes to all branches.

git push

Reseting the Working Copy back to how it is in the Repository

In order to delete new files that you don't want in the repository run:

git clean -f -d

Check if your in master:

git branch

If you are in no branch run:

git checkout -f master

else you can simply run:

git checkout -f

How to Remove a Submodule

There are three traces of a submodule. For the first two are text files. Edit them and remove the lines associated with that submodule:

.gitmodules
.git/config

Then you have to remove the submodule entry in the index/commit. To do that run:

git rm --cached path/to/submodule

Note: Do not put a trailing slash at the end of path. If you put a trailing slash at the end of the command, it will fail.