Using GitHub

This page shows some github commands used frequently in a collaborative code development project such as nptool or midas2nptool ot the T40 code repo. Github is also effective when a sole developer wants to keep track of his code progress and versioning. In the following sections, nptool will be used as an example, however with minor changes, the same commands can be applied to midas2nptool or any other project. To use github you need an account, to contribute to a project you need writing access granted by Adrien for nptool and mida2nptool and Ryan for T40 repo. A nice git-cheat-sheet can be found and more learning material here.

Cloning
First clone the package from github using these lines git init                                            // this will initialise your local repo with .git files git clone https://github.com/adrien-matta/nptool                    // or replace "nptool" by "midas2nptool" Output example Cloning into 'nptool'...    remote: Counting objects: 23186, done. remote: Compressing objects: 100% (51/51), done. remote: Total 23186 (delta 16), reused 0 (delta 0), pack-reused 23135 Receiving objects: 100% (23186/23186), 54.58 MiB | 14.34 MiB/s, done. Resolving deltas: 100% (17515/17515), done. Checking connectivity... done.

Local branches
By default, your local directory will have one branch called master. You can think of branches as sub-directories to your local machine main directory. To list the branches on your machine type git branch (-v)                // v for verbose for info Typical (default) output * master You can create more branches and use them to develop several features of the code without "perturbing" the master. Once your feature is working well, you can merge your local branches.

Remote repositories
Every repo has a name and a URL, and of course branches. To show remote github repos that are connected to your local one. git remote (-v)                // v for verbose Output example origin   https://github.com/adrien-matta/nptool (fetch) origin   https://github.com/adrien-matta/nptool (push) This means that you can "access" the main github repo by using the word "origin" in your commands whenever you want to update the project on your machine (see pull command) or make updates to the main repo on github (see push command).

Current changes status
This particular command is very useful and is frequently used to check what are the changes that you have made recently to your code. It will tell you what are the files that are modified, what the files that are added, and what are the files that has been modified (or created) but are not tracked. In this contest, a un-tracked file is simply only exist in your local repo, if you want it to be part of the project and be used by all other collaborators you need use the git add command explained below. To show the "status" of your current local directory type git status Th output should look similar to the following On branch [branch-name] Your branch is up-to-date with '[remote-repo-name]/[remote-branch-name]'. Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) modified:  ../file0.cxx                         // These files were modified modified:  ../file1.cxx                         // but not added yet Untracked files: (use "git add ..." to include in what will be committed) ../file3                                        // These files were newly created or modified ../../file4                                     // but they are un-tracked Once you add a files, another  git status should give this output

On branch [branch-name] Your branch is up-to-date with '[remote-repo-name]/[remote-branch-name]' Changes to be committed: (use "git reset HEAD ..." to unstage)      // Simply use this command to un-add any file with name modified:  ../file1.cxx                    // When you commit and push (see below for explanation)),  to                                                         // the github repo only this file will be taken into account!    Changes not staged for commit:      (use "git add ..." to update what will be committed)     (use "git checkout -- ..." to discard changes in working directory)           modified:   ../file0.cxx                                                      // Notice the absence of file "../file1.cxx" from this list    Untracked files:      (use "git add ..." to include in what will be committed)           ../file3            ../../file4

Updating your code
It is very important to update your local project with the contributions of other collaborators. - To copy over the changes the merge them with your local machine version git pull origin NPTool.2.dev     // origin is the remote-repo, NPTool.2.dev is the branch within this repo, - If all is up-to-date you should see this message in the terminal From https://github.com/adrien-matta/nptool * branch           NPTool.2.dev -> FETCH_HEAD Already up-to-date. Otherwise if the changes made by others are not in conflict with your code you should see a similar message with some stats on all the files that have been changed.

Solving conflicts
In case of conflicts, git will point out the files that need to be addressed. The conflict message look similar to this remote: Counting objects: 398, done. remote: Compressing objects: 100% (90/90), done. remote: Total 398 (delta 191), reused 158 (delta 158), pack-reused 149 Receiving objects: 100% (398/398), 171.47 KiB | 0 bytes/s, done. Resolving deltas: 100% (268/268), completed with 91 local objects. From https://github.com/adrien-matta/nptool * branch           NPTool.2.dev -> FETCH_HEAD 3bdceb6..c146567 NPTool.2.dev -> origin/NPTool.2.dev error: Your local changes to the following files would be overwritten by merge:    // file(s) has been changed but not commited Projects/T40/T40.detector            // The list of files in conflict, in this case only one Please, commit your changes or stash them before you can merge. Aborting

Open the file in your code editor. You will notice that some part of the code are duplicated in two blocks, one containing the current version and another containing the remote version. The format will be something like this: <<<<<<< HEAD        // conflict markers are in bold //    // local code block //    //     =======     //     // remote code block in conflict //    //      >>>>>>> 3bdceb6..c146567  // This expression is an ID of the version you are trying to merge with (see error message above)

It's easy to go through them by looking for the keyword "HEAD" in the conflicted file. [Solving the conflict] is to choose which one of these two blocks you want to keep (or even picking lines from both) and delete the other WITH the conflict markers. Once you solve all the conflicts, you have to commit the changes and the push them (see below). If there's no conflicts, you simply have to commit the files mentioned in the error. This way git will "keep" these changes in the history and nothing is lost.

Commiting then pushing your changes
Roughly speaking commit here means save/tag/archive. Github will always protect your code from being overridden by keeping a copy of all the last changes and by-assigning a tag or a reference for these changes. It is like when you hit "save" in a word-document for example but more elaborate. I our case, git will keep a history of your project everytime a "commit" was made. That's wahy you need to commit frequently. Commiting the file does not mean it has been merged with the main github repo, it only means that you will never loose this copy of your project on your local machine. The normal flow of github session would be something like this (see below for commands): 1. make changes to a group of files. 2. add the files you want to commit git add file1 file2 file3 3. commit the files and write a comment or a hint about what has been made, e.g. "fixed reading bug" or "adding addback scheme" (all on the same command) git commit -m " This is your message about what have you done, don't forget the quotation marks" 4. push your changes/files to the remote main github repo. git push origin  most of the time  is by default called "master", however this can be changed depending on the project. In NPTool we normaly push on repo origin and  NPTool.2.dev git push origin NPtool.2.dev

Rejected push
Sometimes if you local repo is not updated, with the changes on the main repo, you might end-up with your push being rejected, you'll get a message similar to the following, ! [rejected]       NPTool.2.dev -> NPTool.2.dev (fetch first) error: failed to push some refs to 'https://github.com/adrien-matta/nptool' hint: Updates were rejected because the remote contains work that you do    hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.

In this case you need to update your code by
 * 1) pull the updates
 * 2) Solve all conflict
 * 3) commit changes
 * 4) and finally push again

Undo changes
This page explain the different ways to undo stuff using git.

using travis
Travis in progress