Using the Repository - Amavan/Project-Redlight GitHub Wiki
A good tutorial for understanding the basics of git can be found here but this page will walk through the basics of getting it set up on your computer and using the repository as well.
Downloading git To begin, you will need to download and install git for your platform of choice
git itself comes with both a terminal and basic GUI interface. Additionally, there are several other visual interfaces for using git available one the various platforms, but it is recommended that you use the terminal as it is more flexible and is the focus of this tutorial.
Setting up the repository To begin, you will need to enter the terminal and navigate to the folder you want the repository to be placed in. (Note: if you are on windows and using the terminal that comes with git this is a Bash (Linux) terminal and does not use the windows terminal commands)
Once in the correct directory, set up the initial repository with:
git init
Once the repository is set up, you will want to create a clone of the remote repository of the project using:
git clone <url> (The url for the repository may be found on the main page of the project page, right above the file viewer)
Now that you have cloned the remote repository it will be placed as a sub-folder in your current working directory so you will want to switch to it now.
Making changes
Now that you have cloned the repository, it will by default point you at the most recent commit to the master branch that was pushed to the server. Seeing as the master branch is our stable release branch, we don't want to add changes there. So we will need to check out the development branch. To see all the remote branches use git branch -a. You should see several branches pop up that look similar to remotes/origin/develop. These are all the remote branches, to work on one of them you will need to set up a local branch that is tied to the remote branch. For our example, we will use the main development branch. To check out a branch tied to a remote branch use git checkout -b <local_name> <remote_name>, so in this case git checkout -b develop remotes/origin/develop. The '-b' option creates a branch and automatically switches you to it. If you ever need to switch between branches, use git checkout <branch> Congratulations, you now have a working copy of the branch to make your changes in.
Pushing changes
After you have done some work in a branch, you'll want to commit and push your changes so they are stored in the remote repository. Begin by committing your changes locally. Git will track all changes to an already existing file for you, but any new files you create will need to be added to the tracker using git add <filename>. Alternatively, you can try using the '-a' flag with commit which should auto commit all changes, but this can be iffy and not always cooperative. Now to locally commit your changes use git commit -m "Some description of changes here". Now that your changes are commit locally, you can commit them to the remote repository using git push origin <branch>. If you don't specify a branch when pushing, git typically defaults to the master branch which should have no changes. Thus you need to specify the branch you've been working in. At times, git may tell you that you're out of date with that branch. In this case use git pull which combines a fetch and merge command to update your branch to the latest version that the remote has, and from there you should be able to push your changes. In rare cases, you may be unable to merge because of a conflict between two files.
In case of conflict When a conflict occurs they must unfortunately be solved manually. However, git does provide a tool to help us tell where conflicts occur. By using git diff <branch_one> <branch_two> you can see where two branches differ, which should point you to your conflict, i.e. git diff develop remotes/origin/develop`. You will then have to figure out how to solve the conflict yourself or talk to the person who made the conflicting commit to figure out a strategy. Luckily, conflicts should occur rarely. If a conflict does occur, and you need additional help resolving it or getting git back on track afterwards, do not hesitate to contact me with questions.
Merging a branch Occasionally, separate branches and not just remote vs local commits will need to be merged together, such as when a feature branch (described below) is considered complete. To do this, first switch back to the branch you want to merge into. So if you are merging a feature into the main development branch, switch to develop using git checkout develop (if you don't have a local develop branch tracking the remote one already, you'll need to set it up now using the before mentioned method). Now that you are in the branch you wish to merge into, merge the feature branch using git merge <branch>. For example, git merge feature_test_feature.
Branch strategy This is just a brief overview of our branch strategy and when you will want to create new branches.
- Master: This is our main branch and should be kept completely stable. This branch is used for releases only and each commit to it should be a release product
- Develop: This is the main development branch and should be kept in a semi-stable state. Small changes such as color or text positioning adjustment may be made to the main branch, but large changes that are made in many steps should go elsewhere. For example, if Josh is working on search and Brad is adding analytics, each should be in their own feature branch. Otherwise, if the search is broken and we have to push a release and thus remove it so the site works, we don't want to have to manually remove all references to it from the code. We can't, however, revert the repository either, because doing so would revert a large portion of the analytics changes. Ideally, each commit in the develop branch should be stable enough to be considered a release candidate, or be very close to it.
- Feature branches: The final main branch type is feature branches. These are not a singular branch, but numerous branches, one for each significant feature as alluded to before. So implementation of search functionality, or analytics, or user testimonials, etc would each have its own feature branch, prefixed with 'feature_'. Create one of these each time you take on a significant feature, and merge it back into develop when the feature is considered complete and stable, and has been tested.