On 12/6/07, Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx> wrote: > > > On Thu, 6 Dec 2007, NightStrike wrote: > > > > No disrespect is meant by this reply. I am just curious (and I am > > probably misunderstanding something).. Why remove all of the > > documentation entirely? Wouldn't it be better to just document it > > more thoroughly? > > Well, part of it is that I don't think "--aggressive" as it is implemented > right now is really almost *ever* the right answer. We could change the > implementation, of course, but generally the right thing to do is to not > use it (tweaking the "--window" and "--depth" manually for the repacking > is likely the more natural thing to do). > > The other part of the answer is that, when you *do* want to do what that > "--aggressive" tries to achieve, it's such a special case event that while > it should probably be documented, I don't think it should necessarily be > documented where it is now (as part of "git gc"), but as part of a much > more technical manual for "deep and subtle tricks you can play". > > > I thought you did a fine job in this post in explaining its purpose, > > when to use it, when not to, etc. Removing the documention seems > > counter-intuitive when you've already gone to the trouble of creating > > good documentation here in this post. > > I'm so used to writing emails, and I *like* trying to explain what is > going on, so I have no problems at all doing that kind of thing. However, > trying to write a manual or man-page or other technical documentation is > something rather different. > > IOW, I like explaining git within the _context_ of a discussion or a > particular problem/issue. But documentation should work regardless of > context (or at least set it up), and that's the part I am not so good at. > > In other words, if somebody (hint hint) thinks my explanation was good and > readable, I'd love for them to try to turn it into real documentation by > editing it up and creating enough context for it! But I'm nort personally > very likely to do that. I'd just send Junio the patch to remove a > misleading part of the documentation we have. hehe.. I'd love to, actually. I can work on it next week. - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
