Feedback outside of the user survey

Hi all,

unfortunately, I did not know there was a survey, so I did not participate in it.

I still want to give some feedback from my experiences with git. From browsing the results [1] of said survey, I see one request being made a lot of times. It's basically my main gripe with git, as well :)

git can do a lot of things, but, as a new user, you are never quite sure where to start. Docs are geared towards advanced users (which is fine), but there is no easy entry point (which is bad).

I would suggest three approaches to fix this:

1) A table/An overview along the lines of "So, you are used to
foo and that is how you do it in git."
For example "What is the equivalent of svn co" (yes, that is an
easy one ;). This should not be limited to things git can do.
svn's ability to pull a subdirectory, which is, ttbomk, lacking
in git, should be included, as well. I am sure there are other
examples [2].

2) A use case repository. "So you want to merge two
branches", etc. This would be a good place to explain the
different ways git offers to do stuff, as well.

3) A tutorial. It does not even have to be as sophisticated
as vimtutor. A simple text file specifying steps to do stuff
would be enough.

Thanks, Richard

[1] http://www.survs.com/app/2/wo/7OeqmUsbjaDuuaLsOCLeSg/0.0.9.3.3.0.1.3.33.1.7.1 [2] http://www.survs.com/app/2/wo/7OeqmUsbjaDuuaLsOCLeSg/0.0.9.3.3.0.1.3.14.1.7.1

On Thu, Oct 16, 2008 at 12:19:36PM +0200, Richard Hartmann wrote:

How about:

  Git - SVN Crash Course
  http://git.or.cz/course/svn.html

How about:

  Git User's Manual
  http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

(though I do think a user-contributed "recipe" database might be useful. Maybe such a thing even exists already and I don't know about it).

How about:

  The Git Tutorial
  http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html

Is there something about these that doesn't meet your criteria? Or did you not know about them (in which case, maybe we need to be more prominently pointing to them)?

-Peff

On Thu, Oct 16, 2008 at 12:28, Jeff King <peff@peff.net> wrote:

In best slapstick fashion, I found the pages you mentioned in 1) and 3) after sending off my email. Maybe they did not exist back when I last looked, maybe they are easier to find now, maybe I was too stupid to look, back then. In any case, those two fit my needs nicely. In fact, I would have said as much on this list if I had not become stuck in reading said docs :)

As to the resource you mention in 2), it is nice, but it does not fit exactly to what I had in mind. You have a lot of snippets and single steps, which is fine. What I was imagining was more like a use case & workflow-driven layout. A basic or complex task could give a short overview of steps, all of which would be hyperlinked to detailed explanations. As a lot (more) documentation seems to exist since I last gave git a serious try, this is probably mainly a work of coming up with workflows and linking to the correct places, not so much of writing any actual new text.

And yes, I think the fact that these newbie-friendly docs exist these days should be pushed more agressively. As you can see from the links in my initial mail, a _lot_ of people have the same misinformation I used to have. That will mainly be due to old knowledge, but the situation exists. Worse, those people will warn others about the lack of starter-level docs, making more people shun git for all the wrong reasons.

An easy step in this direction might be to _prominently_ display direct links to the newbie docs on the entry points, for most users. I.e. the main site [1] and the wiki [2] along with the FAQ. I would edit the wiki myself, but I could not find MoinMaster:MoinPagesEditorGroup nor MoinMaster anywhere in said wiki, thus decided to heed the warning & not edit at all.

Richard

[1] http://git.or.cz/ [2] http://git.or.cz/gitwiki

On Thu, Oct 16, 2008 at 12:19:36PM +0200, Richard Hartmann wrote:

Pulling a subdirectory with svn is possible because svn (and others like it) tracks your files and directories. Git, on the other hand, tracks the _content_ of the files in the repo. The information that Git presents (logs, diff's, file contents, etc.) is built from objects that are created from content you add to the repo.

Pulling a subdirectory and thereby excluding the files that make up the content that git used to build its structures in the first place, is something that I don't think would make sense.

I know from an external point of view, it seems pulling a subdir wouldn't be a big deal; but if you look at git internals, you start to realize why it's an option that isn't on the table.

Someone please correct me if I'm wrong here.

On Thu, Oct 16, 2008 at 13:56, Garry Dolley <gdolley@arpnetworks.com> wrote:

That's my understanding as well. And you can simply branch out a subdir when you want to work on it. I am not saying this should be changed, just that it should be mention in The Big Overview.

Richard

Richard Hartmann wrote:

Hm, I don't see a fundamental technical problem which would prevent one from implementing the ability to checkout only a subdirectory into the working directory (i.e. to add options to Git to make it reflect the working directory as being a subdirectory of what is in Git's database). At this level I don't see anything inherently different from SVN--except maybe for directory renames: if someone else is renaming the directory you've checked out, what should happend with your checkout? Git's filebased rename tracking would just lead to everything vanishing from your checkout. I don't know what happens in SVN, maybe it keeps track of the directory rename and still sends you the changes of the directory you've checked out even if it has now a different name on the server?

Anyway, an unavoidable difference is that you have to always clone the whole Git *database*. With SVN the database stays on the server, with Git it is being cloned. Just as I expect SVN to need the whole database to be able to work (tracking renames across directories etc.), Git needs the whole database too. So implementing subdirectory workingdir checkouts wouldn't help reduce the bandwidth and storage necessary for getting at the database.

I guess what you are referring to is

 $ git clone git://foo.com/bar.git
 $ cd bar
 $ rm -rf *
 $ git checkout somesubdir

Now you've got only somesubdir/ below bar/. This solves the rename problem insofar, as somesubdir will just be renamed if someone else commits a "git mv somesubdir somethingelse" and you pull that change. But there's also another caveat: "git status" will of course report the other files as deleted, which is an accident waiting to happen when you next run "git commit -a".

(In any case, this is just thinking louder than I deserve, as there's no code at all in Git written by me.)

Christian.

On Thu, Oct 16, 2008 at 10:32:56PM +0200, Christian Jaeger wrote:

Right, but I think cloning the entire git database just to get a subdir is a fundamental technical problem. It's no different than git-clone + checkout + rm -rf <what I don't want in working tree>

In that sense, git already has support for cloning subdirectories, which is why I don't think this method applies to what the original post author meant when they referred to "support for cloning sub directories".

:)

Garry Dolley wrote:

We're in "violent agreement" here.

I just think it's worth pointing out the difference between the working dir and the database. It should be as easy to implement checking out subdirectories in Git as it was in SVN (except, again, that, iff directory renames should be tracked, some code would have to be written to find out about directory renames, which SVN solves in a simpler way by just requiring that the user specifies renames explicitely). It's worth pointing out that working directory checkouts and database cloning are separate operatoins and it's only the database cloning which is, per definition (as it is a distributed VCS) different from SVN.

If you really wanted, I suppose you could additionally look into implementing a kind of shallow cloning that only copies objects over the wire which are necessary for representing the subdirectory you're interested in.

Christian.

Christian Jaeger wrote:

So what do you do when one such commit also affects something outside the subdirectory?

Andreas Ericsson wrote:

You haven't said what you mean with "affect".

Since the point is that you do not want to see any effect to be made nor described if it is about something outside the subdirectory, the program would just not look at those?

Did you mean, new commits to be made from changed subdirectory contents? The stuff outside the subdirectory would just be kept the same and thus again doesn't need to be present locally.

Did you mean merging branches where one or more of the branches have changes outside the working directory? As long as the changes from the branches don't touch any of the same files (outside the subworkingdirectory), there's no need to fetch the files' contents, the program is only interested in the changes in the directory listings (thus directory objects). Now if there *are* changes to the same files (and outside the subworkingdirectory), the program would certainly need to fetch those contents, too, to be able to create the new contents. Would it require a place in the working directory? Yes if there are conflicts which need to be resolved manually, since it needs a place to put the conflicts to ask the user to resolve. So I guess it boils down to SVN having a different notion of what a merge entails?

Christian.

Christian Jaeger wrote:

I mean "how would you handle a commit (and its tree-object) that updates all Makefiles in, for example, the Linux kernel project?". Those files are spread far and wide, and you'd want that change to *your* tree, but getting it into your tree either means you need to rewrite the tree (and thereby the commit) itself to get rid of uninteresting blob's from the tree, and you'd also have to prune the tree to not reveal the directory layout of the rest of the repository.

I take it parentage could be resolved by a ridiculously large grafts-file.

What you'd end up with wouldn't be a git repository at all anymore. It would be a "stump", as it'd be missing large parts of the tree entirely. I'm unsure just how much you'd have to compute to be able to use such a stump to incorporate your changes with other users again, but I doubt it would be trivial to implement. Good thing it's not my itch, really.

Andreas Ericsson wrote:

You have said "either" but not "or".

Hm, not sure whether you mean to rescue the situation with rewritten commits here -- but hell no, I certainly don't mean to have different commit objects for different clones/checkouts.

That was my point, yes.

I've been suggesting it to Garry :)

Maybe whoever writes up something on the wiki regarding subdirectory checkouts in SVN versus Git could still care about what the "fundamental technical" limits are versus what the current implementation (or practicalness) imposes. It will be both a more enlightening and potentially more future-proof explanation then.

Christian.

Christian Jaeger wrote:

"or end up transferring all objects on the wire anyway".

Then you'll be transferring all objects over the wire anyway, so there goes that idea.

That's partially implemented, I think (google for Nguy (or something, I'm not very god with asian names), but your original suggestion said to save on transferring objects from one machine to another, which will play poorly with git's object database and which you're now arguing against.

Please make up your mind.

Andreas Ericsson wrote:

Why? Again, care to differentiate between technical feasibility and current implementation.

I did make a list of cases in my pre-previous email which tried to go through the implications.

That's not enough information for me to find what you've had in mind. "stump Nguy site:marc.info" doesn't yield a result with Google.

Yes

Why, if we seem to already have agreed that the object database would be a "stump"? It may play poorly with the current implementation of the database maintainance code, but I don't see why it would play poorly with the database's data structure design.

I don't get this part of the sentence.

I did (3 mails ago) say, "(one) could additionally look into implementing a kind of shallow cloning". When you said that the kind of repository I'm "arguing" for would be a "stump", that sounded exactly what I've meant, in the same sense that a shallow clone creates a repository that is missing part of the tree (or maybe DAG is a better term). So I said "That was my point, yes", maybe I should have said "That's what I've meant when I was saying a 'kind of shallow cloning'." Ok? I might miss some fine points in the english language as I'm not a native speaker.

About what?

Do you mean whether I want to implement the idea? Then no, I don't see myself contributing any code for this. I certainly don't have a use case personally where it would pay off. My motivation to contributing to this thread was to point out that there is, afaik, nothing inherent in the Git design (at least the database) which would absolutely prevent one from implementing subdirectory checkouts (including even saving on bandwith by doing some kind of shallow / stump / lazy cloning).

Christian.

Christian Jaeger wrote:

I think it was this detail:

which I have been leaving under the carpet in my previous mails; i.e. when doing merges, Git may need additional objects which haven't been fetched by just fetching the branches's subdirectory parts, so merges can't generally be done offline anymore. This is certainly a departure from the current idea; and if you don't want to depart from that, then yes, you'd need basically the whole database in advance or merges wouldn't be possible. So I think I understand why you said "Then you'll be transferring all objects over the wire anyway", you did assume that there would be no such thing as on-demand / lazy fetching of missing objects.

Christian.

Christian Jaeger <christian@jaeger.mine.nu> writes:

I think Andreas is referring to nd/narrow topic currently parked in 'pu'.

$ git log next..36aa66d^2

Junio C Hamano wrote:

Thanks. This looks nice.

(It is implementing the partial, or "sparse" as Nguyễn calls it, checkouts. So it seems the more useful of the two ideas is basically already done, at least in the sense of saving space for the checkout. It won't 'move'/'mount' the subdirectory to the top of the working directory if only a subdirectory is wanted, but as I've already realized and written, Git may require a full working directory anyway for interaction with the user during merging, and a symlink can be used instead to 'mount' the subdirectory where the user wants it (if the OS supports that). Straightforward solution.)

Christian.