git workflow comments and questions

[tcraig]

I have a couple questions and comments on the workflow that I think should be addressed in the workflow document.Is it correct to say the svn checkout of the cime directory is just a static snapshot with no connection to any of the git features?What's the recommended process for "switching" my CESM sandbox from cime in svn to cime from github so I can use all the git features including commit, branch, and push/pull?I'm confused about how the github repo and the local repo interact.  When I push back to the github repo, does my entire local repo history, branches, tags, etc get pushed into the github repo or am I just creating a new snapshot in the github repo?How do groups of people collaborate in practice?  This is not addressed at all yet. 

 

[jedwards]

The svn checkout is just a snapshot.   You would remove this directory and use git clone to check it out again.  To make sure that youare on the right tag you should do git checkout cimex.y.z where x.y.z is the tag refered to in the svn externals.   When you push back to the github remote it pushes back the branch you are currently on with it's history.    If you want to colaborate on a branch we are recommending that you fork the repository into your own copy on github, create a tracking branch there and share that branch.    - Jim

 

[santos]

> When I push back to the github repo, does my entire local repo history, branches, tags, etc get pushed into the github repo or am I just creating a new snapshot in the github repo?I just added a brief mention of how to push tags, since you reminded me. Also a bit about working on multiple machines. The old behavior for git is that, if you just say "git push origin", it will push all local branches that have the same name as remote branches. This was pretty error-prone, so most people change the "push.default" config option so that only the current branch is pushed, which is what we tell people to do in the document. In Git 2.0, this safer behavior is the default.For most commands in Git that involve pushing, pulling, or merging, all of the history is retained. So if you make several commits and push a branch to your fork on GitHub, all of the commits in the history of that specific branch are synced with the history on the remote. I've tried to make this a little more clear in the document in section 9, though any specific suggestions about better phrasing are welcome.> How do groups of people collaborate in practice?Well, of course the easiest thing is to make fairly incremental changes, and simply merge back to the master in CESM-Development as often as possible. But I'm guessing that what you really are asking about is a long-term branch, where several people want to jointly develop some feature on a branch outside of the CESM-Development master.We haven't discussed this in the document because we've been focusing on basic git commands, but I think that one simple way you could do this is by creating a fork on GitHub, and then adding the other people who need write access as collaborators. The way to do this is to go to the main page of your fork and click the "Settings" button there on the bottom of the right sidebar. Then click on "Collaborators" on the left sidebar, enter your password if it asks you, and type the GitHub username of the person you want to add in the text box. Once added as a collaborator, the other user will be able to push to the repo just like you can. (Alternatively, if you have a big group that needs more complex permissions settings, you can go and create your own GitHub organization and make a fork there.)If you have multiple people pushing to the same branch in the same repo, you will find that sometimes "git push" doesn't work, because the branch you're pushing to has been modified by someone else. I think the message mentions that you can override this using "git push --force", but don't do that, because if you do the other person's changes will be lost. Instead what you want to do is fetch those changes and merge them locally, then push once you have a merged version of the two commits.

 

[tcraig]

This seems like a useful piece of information for creating a branch from a specific tag, which we will often want to do in cime.  From the end of section 2.6 in the git-svn book, http://git-scm.com/book/en/v2/Git-Basics-Tagging#Checking-out-Tags---------You can’t really check out a tag in Git, since they can’t be moved around. If you want to put a version of your repository in your working directory that looks like a specific tag, you can create a new branch at a specific tag with

git checkout -b [branchname] [tagname]

:$ git checkout -b version2 v2.0.0
Switched to a new branch 'version2'

-----------------

so, i did

git checkout -b mosart cime0.3.34

because I wanted to branch from the last beta tag. then like in svn, followed that up with

git tag -a mosart_n00_cime0.3.34 -m "mosart baseline tag from cime0.3.34"

so, i am on the branch (git status) and i can see there is a tag (git tag --list) and i can compare my sandbox
against the original tag (git diff cime0.3.34).

Just a couple follow up questions. When I run git tag, is that being stored in the local repository immediately
or do I need to commit that? Is that tag associated with what's in my sandbox or the last commit from the repo?
In other words, if I want to commit some code changes and tag it, will these result in the same thing?

change code -> git tag -> git commit
change code -> git commit -> git tag
what is the tag operating on and where?

 

[jedwards]

git tag is storing in the local repo immediatly - and tags your current commited code so git commit followed by git tag is not the same as git tag followed by git commit.  To push a tag you need to use the --tag option to git push.   

 

[santos]

Just to elaborate, using the "--tags" option will push all your tags, whereas "git push origin tagname" will push just the single tag that you name (and is in the doc now).

 

[tcraig]

So I guess the idea is that the github repo could contain just a subset of the local repository history?  Is the idea to just push specific tags back to github?  What if I want to push an entire branch and all the tags on just that branch to support collaboration on that branch?

 

[santos]

Yes, the GitHub repo could just contain a subset of the local repository history, if you have local changes that are private, or changes that are just specific to something you're trying out on a particular machine and are probably not relevant to others.If I'm pushing to my particular fork, I usually push everything with "git push --tags origin", because usually I want all the tags and because I'm lazy. However, if you are tagging in an "official" repo, i.e. the CESM-Development CIME instead of your own fork, you do not want to push any tags that only belong in your own fork. So you probably want to either list the tags explicitly ("git push origin tag-name"), or maybe push only the tags from the history of a certain branch ("git push --follow-tags origin branch-name"). I deliberately didn't mention that last option in the document, because it's not going to be relevant to CIME very often, and you should probably be pretty confident that you know what you're doing before relying on it.