Git Tutorial
AttachmentsQuestions? Go to the #infrastructure-deveops channel on Slack: Chat for E3SM
Teach Yourself git:
For those new to git, there is a wealth of information on the web.
Here are a few of the E3SM Infrastructure team's favorite sites to start with:
Basic Git
Git: the simple guide - includes pdf cheat sheet.
Git for computer scientists - graphical intro to the Git data model
Specific git features
Git Pretty what to do if you have a mess of development in your repo.
Here are a few sites that provide information on how to properly format commit messages. This step is very important because several git commands rely on this formatting.
E3SM-related Lessons
The Interactive tutorial on branching is an excellent resource. We have created some exercises for workflow steps seen in E3SM
Hands-on Tutorials:
These are being organized on a volunteer basis by individuals at the labs.
LANL - Doug Jacobsen (Unlicensed)
Sildes: https://docs.google.com/presentation/d/1syVrLb-6F-DFcrlRKOVCfSm8-LfqEsF8e9gu-I8_6tE/edit?usp=sharing
LBNL - Jeffrey Johnson (Unlicensed) date/time/place
ANL - Jed Brown (Unlicensed) Aug 6, 2014 / 3:30pm-5pm / Building 241, A323 (PDF slides)
The SE-team highly recommends using the hands-on tutorial material prepared by the Software Carpentry organization.
Miscellaneous Tips
Philip's Idiosyncratic Git Information Store (PIGIT) (including solution to X11 forwarding warnings)
Comments
I just went through the two ACME-related lessons (as well as the beginner-intermediate levels of the above-linked git tutorial). Thanks for setting this up. One question. What is 'next' supposed to actually represent in the ACME repo world? I wasn't quite clear on that.
It exposes parallelism in the integration process so that comprehensive test suites do not have to be run separately for every merge to 'master'. It is sort of a sandbox where we can watch new features interact and see the results of more expensive tests before needing to make the high-pressure decision to merge to 'master' (at which point any bugs or necessary changes cause disruption for new development and could be used in science results).
Hi Jed Brown (Unlicensed) and Doug Jacobsen (Unlicensed),
I have a questions regarding merging changes in master branch into my branch. I have a branch say "polar-mods" which is branched out from the master branch several weeks back and made one commit to my branch. In the meanwhile several commits were made to the master branch. I want to include all those commits into my branch. There are two ways to do it, "merge" and "rebase". I read in git documentation that "rebase" is a cleaner way to achieve this as it will rewrite history in a cleaner way. The documentation warns that "rebase" should not be used if multiple people are working on the branch (as it rewrites history). This branch will be used by PNNL and LLNL. Should I use "merge" to achieve this?
If other people are using your branch, rebasing would disrupt them so you should avoid it. What exactly do you want from upstream ('master')? You shouldn't merge from upstream just because things have happened there, you should be able to name a specific change that is necessary for your branch to achieve its goal (which is to complete a feature so that it can be merged to 'master'). Once that feature has been identified, you should check whether you can get that feature with fewer side-effects. For example, if the commits you need are in fact bug fixes developed in a topic branch from 'maint', you can merge the topic branch to get the bug fixes and nothing else. That should be preferred. If there are no other options for getting the commits you need, you should merge 'master' and write a commit message that states what you are getting and why you need it in your branch.
Thanks Jed Brown (Unlicensed). My intention was to stay as close as possible to the head of the master branch to avoid having to deal with conflicts at a later point. Before pushing new modifications to my branch, I wanted to sync my branch with the master branch, add new modifications and then push those to my branch. As of now, there is nothing in the master branch which I need to proceed with my work. Is it a desirable approach? I would like to get your advise on this.
Just keep working in your branch and resist the urge to constantly "sync" with 'master'.You can test a "throw-away merge" if you're really nervous about conflicts:git checkout --detach origin/master
git merge your/branch-name
If it merges cleanly or with "simple" conflicts, just go back to your branch and don't worry. If you have conflicts, decide how to resolve the conflicts with as few side-effects as possible (perhaps by merging the topic branch that introduced the conflicts into your branch).
Thanks Jed. It was really helpful.
Hi Jed Brown (Unlicensed),
I too had the same question (i.e. staying close with master) as raised by Balwinder Singh (Unlicensed) here. Is there a place where the team is documenting such code development philosophy for ACME? Thanks.
I'm my opinion the Development Reference would be more easy to navigate if links to the 14 points are included at the top of the page.
Thanks for the feedback. I'll make an editing pass this week.
I'm pinging you in case you are interested in experimenting with the Git tutorial material. Note that developers of new features will not have to deal with merging. Integrators should understand the branching model and style guidelines.