diff --git a/documentation/how_to_use_git.md b/documentation/how_to_use_git.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..a668a590606e7911792de3e9ab1fdea2fe3cb111 100644 --- a/documentation/how_to_use_git.md +++ b/documentation/how_to_use_git.md @@ -0,0 +1,102 @@ +# How to use Git +This project uses Git. That means that if you plan to make any edits to the +project, you'll be using some Git command. + +## Where is everything? +Everything is on the master branch. In git, a _branch_ is like a timeline of +the project. The timeline is composed of incremental changes, called _commits_. +In the case of the master branch, these commits go all the way back to the +beginning of the project. Nobody can delete history on the master branch. Once a +commit is added, it is permanent. When you browse files on Gitlab, you are +likely looking at the most recent state of the master branch. + +## How do I make changes? +To make a change to the project, you'll need to make a commit to the master +branch. You can technically make edits to files right in Gitlab, but most +people prefer to copy the entire Git project locally to their PC, make +edits, and then copy those changes back to the main Git project on Gitlab. + +### Using your own computer to make changes +#### Setup (Only need to do once) +First, [setup an SSH key](https://git.ece.iastate.edu/help/ssh/README). + +Clone the project: +``` +git clone git@git.ece.iastate.edu:danc/MicroCART.git +``` +That was easy. You can enter the directory you just made, and see all of the +project files. + +#### Actually making changes +First, sync to be sure your personal computer has the most recent state of +master on Gitlab. +``` +git pull origin master +``` +Now you can make your edits. Do whatever you like to the project. + +When you are finished, look over the changes you have made. +``` +git status +git diff +``` +If you are happy with you changes, it is time to prepare a commit. + +Stage each changed file in order to commit them: +``` +git add (name your files here) +``` +If you don't want list out every file you changed, you can do clever things +like using the entire folder where the changed files are (sometimes people will +use `.` for the current directory). + +Look at the files you have staged: +``` +git status +``` + +If all looks well, it is time to commit: +``` +git commit -m "describe your changes here" +``` +If you'd prefer to use a text editor to write your commit message, drop the `-m` +part. + +You can look at the commit you just made: +``` +git commit log -n 3 +``` + +Now we need to sync your master branch with the master branch on Gitlab. +``` +git push origin master +``` + +It's likely someone else has made a change since your last sync, so you may get +an error saying your master is out of date. In that case, sync your master with +Gitlab's master again. + +``` +git pull origin master +``` + +If you happend to be editing the same lines as someone else, you'll get the +so-called "merge conflicts." In that case, look at the error output to determine +which files have conflicts, and go edit those files. You'll have to choose which +changes to keep. At the end of the day, you need to get rid of the `<<<` lines. +Once you have fixed everything, `git add` those changes and `git commit` to +create a merge commit. Maybe do another `git log` after everything to be sure +everything makes sense. + +Once you have synced your master with Gitlab's master again, sync Gitlab's +master with your master again: +``` +git push origin master +``` + +If all succeeds, you should be able to see your commit on Gitlab. + +## Other workflows +What we just described is the bare minimum Git workflow. Most people don't like +working this way. We encourage you to research other workflows, like a Git +branching workflow.