Re: Git User's Survey 2007 unfinished summary continued

["J. Bruce Fields" <bfields@fieldses.org>]

On Sun, Oct 14, 2007 at 11:12:07AM -0700, Steven Grimm wrote:
> But that's just an aspect of a more general fact: it's hard to use git 
> without getting exposed to the plumbing at least a little. Another example 
> is the manpages: try to look up the commonly-used options to "git diff" 
> (porcelain) and you will be forced to learn about "git rev-parse" 
> (plumbing).

As "plumbing" goes, "git rev-parse" isn't that bad, and the reference
here (to the "SPECIFYING REVISIONS" section) strikes me as reasonable.
We could factor out the common documentation into a separate (hopefully
more user-friendly) manpage about specifying revisions, I guess, and
refer to it everywhere instead of git-rev-parse.  I don't know--any
other ideas?

> It's possible git's introductory documentation should delay talking 
> about "git branch" until later, and start off talking about how to work 
> with one (checked out) branch per repo.

One frequent use case is the case of a tester that wants to try out a
bugfix in some topic branch.  You want to tell them: "please test the
fix-that-bug branch in git://myproject.org/~me/repo.git".  They need to
get that checked out somehow.  And they should be able to do it without
re-cloning every time.

That's one motivation, among others, for including git-branch (and
git-remote) very early.

Though actually the quickest way to checkout an arbitrary revision is
with detached heads, and that doesn't require learning git-branch right
away.  I've tried rewriting the user-manual start that way but wasn't
happy with the result and didn't get too far.  (See
git://linux-nfs.org/~bfields/git.git docwork-detached.)

> Update to a dirty working copy. I think there's a tendency in these parts 
> to vastly underestimate the importance of being able to pull down updates 
> from a master repository while you're in the middle of development. 
> Mercurial's equivalent to bare "git pull", namely "hg pull" followed by "hg 
> update", works fine if you have edits in your working copy; if there are 
> conflicting changes, it pops you into a conflict resolution UI (or adds 
> conflict markers, depending on your settings) and you continue on your 
> merry way after resolving everything. This workflow is really common, 
> especially in corporate settings where there's very fine-grained 
> collaboration going on during initial development (a huge difference from 
> the open-source world where most of the time it's just one person doing an 
> initial prototype.) Right now working this way is a pain in git. Less so 
> now that we have "git stash", but it could still be much, much smoother.

I'm lost--how is "hg pull" different from "git pull" in this respect?

> Verbosity. IMO Mercurial swings too far in this direction, but in general 
> it's either completely silent or very terse in its output.

Yes, there's a lot of low-hanging fruit here for someone that's
interested in streamlining the default git command output.  The
challenge is to get it a little terser while still being helpful (and
preserving progress meters, and not obscuring what's going on any more
than necessary).

--b.