[DFDL-WG] Action 200 - Workflows - Git for central repo of DFDL schemas at github (was Re: Git commit policies)

[Mike Beckerle]

Please look at the terminology email I sent prior along with this one.

The simplest possible one-branch-only straight-line only git workflow is
described below:

git clone - this is a one time operation to create local repository copy
from central one

Note: do NOT put this clone repository directory INSIDE your eclipse
workspace, nor should you point your eclipse at a directory inside this
local repository as its workspace. Keep things separate. I have two git
repositories cloned on my machine.  One is in ~/git/fouo another is in
~/daffodil/git/daffodil. My eclipse workspace is elsewhere. Eclipse (with
eGit) will happily point at a project directory inside the repository, but
keep its settings and such elsewhere. (Project specific settings end up in
the project of course. They have to. Treat them in git like any other
files/directories.)

The "git" directory name is just a convention, the repository is usually
the directory beneath that. (It will have a ".git" hidden directory in it.)
You will have to be cd to this repository directory to issue any of the git
commands.

Here's the repeating workflow:

   1. edit files, test stuff in the usual ways (nothing to do with git)
   2. git status - shows you list of untracked files, and changes that are
   ready to commit (use this command often)
   3. git add - any new (i.e., untracked) files so git knows to track them
   4. git commit - locally packages changes into a unit/change-set
   5. repeat from step 1 as many times as you want. When you want to
   publish your changes for others continue with the next step.
   6. optional step - zip/tar your local repository for safe keeping (for
   the paranoid - or git newby)
   7. git fetch - pulls all outstanding changes from central repository
   (doesn't merge anything)
   8. git rebase - begins the merge-the-code sub-loop here. Rebase replays
   your commits one by one on top of latest from central repo.
      1. if rebase finished with no conflicts, leave this sub-loop
      2. edit files to fix any conflicts (nothing to do with git)
      3. git add - conflicted files that you merged have to be re-added
      (tells git you have merged them)
      4. git rebase --continue - carry out more replay of your committed
      changes
      5. go to step 5.1 (top of this sub loop)
      9. fix remaining problems that aren't just merge conflicts. Test.
   (nothing to do with git)
   10. git commit - packages up anything changed as part of the merge.
   11. Decide - your local repository is now current with latest and
   greatest with your changes on top
      1. If you want to continue working locally, go to step 1.
      2. If your stuff is at a good point and you want to push your changes
      to the central repository for others to see, then go to the next step.
   12. git push - move your changes to the central repository.
   13. Note prior step will probably succeed, but if someone beats you to
   the push, you will be rejected, so repeat from step 7.
   14. You are done. Repeat for your next changes.

The above workflow achieves something similar to subversion with no
branches being created. You have to have your changes merged (we call it
rebased) properly on top of the latest and greatest before you are able to
push your changes back to the central repository.

A useful technique: git fetch and git rebase really often even before you
intend to push your changes (see step 11 above). This keeps your state
close to that of the central repository and keeps the amount of conflict
resolution low.

In my experience, it is possible to lose local changes and files using git
- usually this happens if they are untracked files. A git expert can
*usually* get things back for you, but when it doubt: just zip/tar up a
copy of your whole local repository. That preserves *everything* allowing
you to go back. I always do this before a complex merge/rebase. It is
easier for me to back out of something by just deleting the whole
repository and un-tar of my save than to figure out the git archaeology
needed to back up to the state I want.

The daffodil open source project uses a more complex git workflow that
accomodates a code-review cycle. This is described here on our Wiki:

https://opensource.ncsa.illinois.edu/confluence/display/DFDL/Development+Workflow

Searching the internet for "git cheat sheet", I found this one is the
simplest but quite a few of them are useful.

http://nakedstartup.com/2010/04/simple-daily-git-workflow (Scroll down.
It's below the fold in a Scribd slide)

There are useful, but all imperfect, graphical git tools. I use eGit mode
in Eclipse a great deal. Others use gitg or qgit, etc.

When I say they are imperfect, it's because it is *not* in my experience,
possible to "live entirely" in one of these graphical tools. You have to
use the command line git sometimes. The daffodil project workflow depends
on this.

Here are the cautions I would give to anyone new to git.

1) commit often. Think of it almost like save.
2) never do any operation while you have uncommitted or untracked files in
your sandbox. Commit first, then do whatever your operation is.
3) the command line 'git status' operation is your friend.

Something I learned recently: git doesn't track empty directories. Add a
".keep" file to them to keep them around.



On Tue, Jan 29, 2013 at 10:46 AM, Tim Kimber <KIMBERT at uk.ibm.com> wrote:

>
> http://stackoverflow.com/questions/3505409/does-there-exist-git-commit-policies-e-g-when-and-what-to-commit
>
> http://git-scm.com/book/ch5-1.html
>
> regards,
>
> Tim Kimber, DFDL Team,
> Hursley, UK
> Internet:  kimbert at uk.ibm.com
> Tel. 01962-816742
> Internal tel. 37246742
>
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number
> 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
>



-- 
Mike Beckerle | OGF DFDL Workgroup Co-Chair | Tresys Technology |
www.tresys.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20130208/aea0a087/attachment.html>