Git(Hub) Development model Using Git(Hub) Summary & Conclusions
SixTrack on GitHub How to use GIT(hub) and the SixTrack development model
Kyrre Sjobak
SixTrack meeting, Sept. 17th 2015
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 1 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Outline
1 Git(Hub)
2 Development model
3 Using Git(Hub)
4 Summary & Conclusions
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 2 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is Git?
A revision control system! Similar to SVN, except. . . Much better support for parallel development in branches Distributed: Everyone has a full copy of the whole repository on their workstation A lot faster An extremely powerful tool Built on straight-forward principles Originally developed by Linus Thorvalds for the Linux kernel Very widely used, scaling from small personal codes to huge projects
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 3 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is Git?
A revision control system! Similar to SVN, except. . . Much better support for parallel development in branches Distributed: Everyone has a full copy of the whole repository on their workstation A lot faster An extremely powerful tool Built on straight-forward principles Originally developed by Linus Thorvalds for the Linux kernel Very widely used, scaling from small personal codes to huge projects
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 3 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is Git?
A revision control system! Similar to SVN, except. . . Much better support for parallel development in branches Distributed: Everyone has a full copy of the whole repository on their workstation A lot faster An extremely powerful tool Built on straight-forward principles Originally developed by Linus Thorvalds for the Linux kernel Very widely used, scaling from small personal codes to huge projects
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 3 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is Git?
A revision control system! Similar to SVN, except. . . Much better support for parallel development in branches Distributed: Everyone has a full copy of the whole repository on their workstation A lot faster An extremely powerful tool Built on straight-forward principles Originally developed by Linus Thorvalds for the Linux kernel Very widely used, scaling from small personal codes to huge projects
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 3 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is GitHub?
Company which offers hosting GIT repositories + tools (issue tracker, wiki, web interface,. . . ) Free for open-source software Recommended for CERN projects which have outside collaborators For closed projects, CERN hosted GitLab is recommended(a). About 11 million users No risk in using an external provider https://github.com due to GIT’s decentralized model.
a) https://cern.service-now.com/service-portal/article.do?n=KB0003132&s=gitlab Kyrre Sjobak SixTrack on GitHub SixTrack meeting 4 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions What is GitHub?
Company which offers hosting GIT repositories + tools (issue tracker, wiki, web interface,. . . ) Free for open-source software Recommended for CERN projects which have outside collaborators For closed projects, CERN hosted GitLab is recommended(a). About 11 million users No risk in using an external provider due to GIT’s decentralized model.
a) https://cern.service-now.com/service-portal/article.do?n=KB0003132&s=gitlab Kyrre Sjobak SixTrack on GitHub SixTrack meeting 4 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (1)
Commit Fork A set of changes, An independent copy of the labeled by a SHA-1 hash repository
Branch Merge A named string of commits Updating one branch using the (label tracks the last commit) changeset in another
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 5 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (1)
Commit Fork A set of changes, An independent copy of the labeled by a SHA-1 hash repository
Branch Merge A named string of commits Updating one branch using the (label tracks the last commit) changeset in another
...
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 5 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (1)
Commit Fork A set of changes, An independent copy of the labeled by a SHA-1 hash repository
Branch Merge A named string of commits Updating one branch using the (label tracks the last commit) changeset in another
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 5 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (1)
Commit Fork A set of changes, An independent copy of the labeled by a SHA-1 hash repository
Branch Merge A named string of commits Updating one branch using the (label tracks the last commit) changeset in another
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 5 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (1)
Commit Fork A set of changes, An independent copy of the labeled by a SHA-1 hash repository
Branch Merge A named string of commits Updating one branch using the (label tracks the last commit) changeset in another
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 5 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Basic GIT concepts (2)
Working copy Remote A working copy may have one or To use the files in the repository, more remotes. When you create you checkout a specific commit. a working copy by cloning a This fills the working directory remote repository (e.g. a GitHub with files in the state described repository), this becomes the by the commit. default remote. You may synchronize your working copy HEAD with these, fetching in commits The currently checked out from them and pushing commits commit. to them.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 6 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Moving from SVN to GIT: Why
Wanted to be able to track multiple parallel branches GIT is faster and more flexible Will make reviewing and merging contributions easier
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 7 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Moving from SVN to GIT: How
Converted the old SVN repository using git svn Needed to supply a list linking SVN usernames to real names+email All old commits were imported Branches and tags recognized Clean-up: Removed references to old SVN repository in metadata Squash commit #193 with #194 (the line-endings oopsie) Testing & dogfooding. . .
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 8 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions For the impatient: SVN ↔ GIT cheat sheet
Download contents of repository: Undo a change: svn checkout URL git revert COMMIT_ID Create a new commit which ↔ git clone URL undoes the changes introduced in COMMIT_ID Update working copy: git reset FILE Reset the contents of the file to last svn update ↔ git pull commited version git clean (-n) Remove untracked files from working See the status of repository: directory (-n: dry-run) svn status ↔ git status svn diff ↔ git diff Branches: svn log ↔ git log Merge two branches: svnstatus Working copy version etc. git merge MERGEFROM Merge branch MERGEFROM into git branch Which branch is in use current branch Change what is tracked: git checkout (-b) BRANCHNAME Switch to branch svn add FILE ↔ git add FILE BRANCHNAME (-b: create it) svn rm FILE ↔ git rm FILE Read the manual: svn mv FILE ↔ git mv FILE svn help COMMAND Commit a change: ↔ git help COMMAND svn commit ↔ git commit FILES && git push
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 9 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch
To merge your code into upstream (for a new master release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch master To merge your code into upstream (for a new master release), create a pull request on GitHub. copy
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch master,feature To merge your code into upstream (for a new master release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories: To add a new feature, create a fork on GitHub. master master In the newly created personal repository, copy create a branch. feature Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories:
To add a new feature, create a fork on GitHub. feature master In the newly created personal repository, master create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. feature Personal repositories: To add a new feature, create a fork on GitHub. master In the newly created personal repository, master create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack master Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. feature Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, master create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack master master Contains the released versions in its master branch. copy Repository maintained by Ricardo and Kyrre. feature Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Our development model
Master repository: Upstream Private https://github.com/SixTrack/SixTrack master master Contains the released versions in its master branch. Repository maintained by Ricardo and Kyrre. Personal repositories: To add a new feature, create a fork on GitHub. In the newly created personal repository, create a branch. Do your changes in this branch, while your master tracks the upstream master. To get the changes from upstream into your branch, merge upstream’s master into your branch To merge your code into upstream (for a new release), create a pull request on GitHub.
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 10 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Overview of the GitHub user interface (1)
Your account
User / Repository
New fork Network Compare and/or create pull request Issues & pull requests Branch Code explorer Clone URL
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 11 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Overview of the GitHub user interface (2)
SHA1
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 12 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Downloading the code
Getting a working copy:
1 cd to suitable folder 2 Creating a working copy which tracks upstream: git clone https://github.com/SixTrack/SixTrack.git Updating the working copy to the latest version:
1 cd to working copy 2 git pull to update1 Checking out a specific version:
1 cd to working copy 2 git pull to update 3 git checkout
1 Go to the main SixTrack GitHub page → Issues https://github.com/SixTrack/SixTrack/issues 2 Check if your bug is already known If so, you may add a comment that you are also affected 3 New issue → Describe the problem, especially: How it behaves Expected behaviour SixTrack version How to reproduce the problem
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 14 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Reporting a bug / requesting a new feature
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 14 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Extending SixTrack
1 Create a github account, set up SSH keys etc. 2 Click the “fork” button and create your new fork 3 Clone your fork to your disk as before (but use your own URL) 4 Create a non-master branch for your new feature: git checkout -b yourBranch2 5 Develop! 6 When you have something good: git status : See which files have changed rel. HEAD git diff : See how they have changed git commit
2To start from old version: Add a SHA1 to the checkout command 3The first time you push a newly created branch, you need to set its remote; add the arguments --set-upstream origin yourBranch Kyrre Sjobak SixTrack on GitHub SixTrack meeting 15 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Keeping your version up to date with the main branch
1 First time only: Add a remote “upstream”: git remote add upstream [email protected]:SixTrack/SixTrack.git 2 Download upstream’s master: git fetch upstream master 3 Check out your master: git checkout master 4 Fast-forward4 merge upstream’s master into your master: git merge upstream/master 5 Merge your master into your feature branch: git checkout featureBranch git merge master
4This you can only do if you have NOT committed to your master branch Kyrre Sjobak SixTrack on GitHub SixTrack meeting 16 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Merging your code into upstream
1 Make sure all your commits in the branch are pushed to GitHub 2 In GitHub’s GUI, navigate to your branch 3 Click “Compare, review, and create pull request” 4 Click “Create pull request” 5 Write something sensible 6 Wait for code review & invitation to coffee meeting to discuss changes 7 Implement requested fixes 8 Celebrate when the pull request is accepted! 9 Delete your branch (remove the nametag) from your repository
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 17 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Merge conflicts (1)
When merging, sometimes merge conflicts arises Happens when the two versions being merged have changed the same lines (or very close by) in the same files since when they split Not scary. Example: Merging master into branch JavierBB
Output of git merge: $ git merge master Auto-merging SixTrack/sixtrack.s CONFLICT (content): Merge conflict in SixTrack/sixtrack.s Auto-merging SixTrack/compareSVN Automatic merge failed; fix conflicts and then commit the result.
Looks like we have a problem. . .
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 18 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Merge conflicts (2)
Output of git status:
$ git status # On branch JavierBB # You have unmerged paths. # (fix conflicts and run "git commit") # # Changes to be committed: # # new file: ../CERN-logo.jpg # new file: ../Doc/physics_manual/bibliography.bib # new file: ../Doc/physics_manual/makefile (etc. — this branch started from a very old version) # new file: LICENCE # modified: README # modified: ast_mask/sixve.ast # modified: ast_mask/track.ast # modified: beauty/count.awk # renamed: compareSS -> compareSVN # modified: make_six (And then comes the problem) # # Unmerged paths: # (use "git add
Problem is in sixtrack.s
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 19 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Merge conflicts (3)
Inside sixtrack.s, find 4 blocks like
<<<<<<< HEAD How it looks like in the new branch ======How it looks like in master >>>>>>> master
These blocks are sourrounded by thousands of lines of successfully merged code. To fix it, edit these blocks such that it works, check that it compiles etc.
Then commit: git commit -a Push: git push
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 20 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Some tricks
Abort a commit: Don’t write any commit message in the editor that comes up Use a specific editor: $ git config –global core.editor “emacs -nw” Use a GUI to explore how your local repository looks like $ git gui In the menu: Repository → Visualize all branch history Fix a bad commit message: git commit --amend Only works if you have not yet pushed! Documentation: git help
We are moving away from SVN and onto GIT for SixTrack’s version control This makes it easier to handle contributions and parallel developments Our chosen development model was presented Tool usage was presented
Some concluding remarks: Commit early and often! Check which branch you have checked out: git branch Everything is local (and safe) until you push If you mess up a repository (a fork), you can just delete it and start anew. Git(Hub) is a great tool for your own projects as well!
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 22 / 22 Git(Hub) Development model Using Git(Hub) Summary & Conclusions Summary and conclusions
We are moving away from SVN and onto GIT for SixTrack’s version control This makes it easier to handle contributions and parallel developments Our chosen development model was presented Tool usage was presented
Some concluding remarks: Commit early and often! Check which branch you have checked out: git branch Everything is local (and safe) until you push If you mess up a repository (a fork), you can just delete it and start anew. Git(Hub) is a great tool for your own projects as well!
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 22 / 22 Merge conflict samples
<<<<<<< HEAD &qbet,qigam,r0,r0a,ram,rdev,rfr,rmean,rph,rsqsum,rsum,rv,tilt,u0, & &xang,xstr,xpl0,xplane,xrms0,zpl0,zrms0,separx,separy double precision mm1,mm2,mm3,mm4,mm5,mm6,mm7,mm8,mm9,mm10,mm11 ======&qbet,qigam,r0,r0a,rdev,rmean,rsqsum,rsum,rv,tilt,u0, & &xang,xstr,xpl0,xplane,xrms0,zpl0,zrms0 >>>>>>> master
<<<<<<< HEAD ======if(kz(i).eq.20) then ptnfac(i)=el(i) el(i)=zero endif !--General >>>>>>> master
<<<<<<< HEAD if(kzz.eq.26.or.kzz.eq.27.or.kzz.eq.28) goto 500 if(kzz.eq.-26.or.kzz.eq.-27.or.kzz.eq.-28) goto 500 ======! JBG RF CC Multipoles to 500 if (abs(kzz).eq.26.or.abs(kzz).eq.27.or.abs(kzz).eq.28) goto 500 >>>>>>> master
Kyrre Sjobak SixTrack on GitHub SixTrack meeting 1 / 1