From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.devel Subject: Re: Apologia for bzr Date: Sat, 04 Jan 2014 14:01:01 +0900 Message-ID: <87a9fcjq7m.fsf@uwakimon.sk.tsukuba.ac.jp> References: <20140102211452.GA28685@c3po> <83d2k9xx1f.fsf@gnu.org> <87fvp4kdoh.fsf@uwakimon.sk.tsukuba.ac.jp> <83iou0wz8s.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Trace: ger.gmane.org 1388811685 11685 80.91.229.3 (4 Jan 2014 05:01:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 4 Jan 2014 05:01:25 +0000 (UTC) Cc: esr@thyrsus.com, kfogel@red-bean.com, toby-dated-1389906911.cc0ede@dr-qubit.org, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jan 04 06:01:30 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VzJMX-00089d-OJ for ged-emacs-devel@m.gmane.org; Sat, 04 Jan 2014 06:01:29 +0100 Original-Received: from localhost ([::1]:53163 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzJMX-0005JT-EV for ged-emacs-devel@m.gmane.org; Sat, 04 Jan 2014 00:01:29 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40938) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzJMN-0005C4-SD for emacs-devel@gnu.org; Sat, 04 Jan 2014 00:01:27 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VzJMG-0003Hu-GZ for emacs-devel@gnu.org; Sat, 04 Jan 2014 00:01:19 -0500 Original-Received: from mgmt2.sk.tsukuba.ac.jp ([130.158.97.224]:58994) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzJM8-0003FP-4b; Sat, 04 Jan 2014 00:01:04 -0500 Original-Received: from uwakimon.sk.tsukuba.ac.jp (uwakimon.sk.tsukuba.ac.jp [130.158.99.156]) by mgmt2.sk.tsukuba.ac.jp (Postfix) with ESMTP id 8844D970A31; Sat, 4 Jan 2014 14:01:01 +0900 (JST) Original-Received: by uwakimon.sk.tsukuba.ac.jp (Postfix, from userid 1000) id 7B8CA1A26F6; Sat, 4 Jan 2014 14:01:01 +0900 (JST) In-Reply-To: <83iou0wz8s.fsf@gnu.org> X-Mailer: VM undefined under 21.5 (beta34) "kale" 2a0f42961ed4 XEmacs Lucid (x86_64-unknown-linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 130.158.97.224 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:167255 Archived-At: Eli Zaretskii writes: > > Eli Zaretskii writes: > > > > > At least in Emacs we have an excuse that the bulk of the > > > terminology developed when no other software provided any similar > > > features; there's no such excuse for git (or bzr or hg). And I replied: > > You're wrong about git, you're arguably right about bzr and hg. > > What, git was the first VCS, and needed to invent a new terminology? Not the first VCS, but certainly a leader in the generation of VCSes first to provide the features that got new terminology (index, fetch, pull, push). For older features (such as commit, diff, and merge) it uses the traditional terminology. > > Git is fundamentally different from bzr and hg, almost as > > different as it is from CVS and RCS. [...] > What does this have to do with clear and comprehensible > documentation? dVCS, being fundamentally different from cVCS, needs new terminology (eg, at least one of the three concepts "commit", "push", and "commit and push" needs a term not used in cVCS). Similarly, git, being fundamentally different from bzr and hg, *needs* more new terminology than they do, specifically "index" and "reset". Inventing it was not avoidable. The rest of that paragraph was justification for the claim that git is different. > I said "rarely used terms". Frequently used terms need to be > understood in advance, by reading the preceding chapters. "Index" and "commit object" are used frequently in git documentation, although perhaps not in the parts you have read. > In any case, buffer and window can be intuitively understood, much > more than "index" and "staging". In fact, some people find "buffer" and "window" very unintuitive (they don't know what a "buffer" is, they think they're looking at a "file" or "document", and "window" means a GUI object, not a subdivision of the GUI object). Others (me, and at least one other person has testified to finding "staging" very intuitive) find "staging" and "index" quite intuitive, thank you very much. > > The git "index" is equally fundamental to git. > > But there is a way to explain what a commit does without ever > mentioning the index, certainly not in the sentence that _defines_ > what a commit is. Sure, but to define commit in git, it also needs to describe what a commit object is, which is (basically) a file containing a copy of the index. If you know what the index is, then you know what a commit object is, and then you know what a commit is. Understanding this is important to understanding the performance characteristics of git, as well as the operation of some features not available in other dVCSes. > > Sure you do; commit hasn't changed. What you now know is what the > > index is: a data structure that contains the same information as a > > commit, but isn't a commit and isn't a working tree, either. > > No, I don't know any of this, because it wasn't explained, not even in > a few words that would help me make it past the obstacle. git help glossary I agree that's inconvenient compared to an Info link, and that the current version of the top-level git man page (which just lists the other man pages) is pretty hideous -- IMO it ought to contain about half the material in the glossary plus a description of the structure of the git object database with a few key terms explained with reference to the object database operations they perform. > No, I'm talking about *the* basic workflow: make changes, then commit > them. Tutorials seldom go beyond that. C'mon, I'm a coauthor of BzrForEmacsDevs, and did my homework (reading other tutorials). You should be able to guess that I know better than that. But taking your claim at face value: that requires no reading of manpages to accomplish in git if you've used any VCS (including RCS) before. So you're just being contentious here. You only run into problems by pretending that git is CVS or bzr if you use facilities like reset (not possible in any other VCS, you have to revert or commit -- both available in git) and rebase (way beyond your "the *basic* workflow"). > > > --unchanged Commit even if nothing has changed. > > > > This makes a lot of sense in Bazaar, because Bazaar makes it hard to > > work nonlinearly without using multiple workspaces. > > I was talking about clear documentation, not about the differences > between git and bzr. git documentation is *clear*[1] if you start by understanding how git's purpose and implementation differs from other VCSes. It's only if you try to force it into your preconception of what a (d)VCS should be that it becomes unclear. *This is precisely why many people have trouble grokking Emacs* -- they try to think about it as something familiar like a wordprocessor or Notepad or a web browser, and when it violates their preconceptions, they turn away from it in disgust. > > > I want some decent reference documentation. > > > > AFAICT, you want your dVCS to be Bazaar. > > It doesn't matter what I want in this case, we all know what I will > get, right? Now that Stefan has spoken, yes, I think we do know. I'm genuinely sorry for the folks who definitely prefer bzr (of whom Stefan is one, of course). It's a damn shame that Shuttleworth pissed off Tom Lord -- who decided quite early on that the git object data base was the way to go, and completely rewrote Arch/tla to use it in his never-published "revc" aka Arch-ng -- and that the Bazaar developers never came to the conclusion Tom did. > Since that's what I will get, I want its documentation to be > helpful. Well, documentation can't help you if you won't help yourself. Those who find the git documentation completely unintelligible are going to have to start by abandoning the idea that git is a poor implementation of Bazaar. (Certainly, it is, but that's not helpful in understanding git or its documentation.) > Please don't misrepresent what I wrote by turning it into another > "git is more powerful than bzr" thread. That is not what I was > talking about. Nor is it what I was talking about. If you want to make suggestions that will improve git documentation[2], you are going to need to accept that although overall it sucks, much of it is already written in an appropriate fashion. It's possible to discuss whether the word "index" needs to be mentioned in the brief description of "git commit"; although the reason for doing so I presented above is valid, on balance it might not be the best brief description. But effective use of git (including understanding what "gurus" are recommending to get a novice out of a wedge) requires the concepts of "index" and "commit object". The fact that bzr doesn't have that concept doesn't mean it's unnecessary in git documentation, only that people who want git to be bzr will think it's unnecessary. > Anyway, I'm beginning to regret that I answered esr's question. I > should have known what kind of "tide" will be unleashed on me. Again, you're mistaking what I'm talking about. I'm also interested in how to make git's documentation more useful to Emacs devs who don't like git. Funding from ORA or not, I'm thinking about taking the git docs and reorganizing and supplementing them the way Nye et al did for the MIT X docs. But if you're going to maintain the attitude that the things in git that aren't in bzr should be moved to appendices so you don't need to learn about them, I'm not going to bother continuing to think about that. Footnotes: [1] I've already acknowledged the poor organization. [2] Maybe Tim O'Reilly will recruit somebody to write the Git Version Control System Series, or the Git: Essential Reference.