From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Apologia for bzr Date: Fri, 03 Jan 2014 23:07:31 +0200 Message-ID: <83iou0wz8s.fsf@gnu.org> References: <20140102211452.GA28685@c3po> <83d2k9xx1f.fsf@gnu.org> <87fvp4kdoh.fsf@uwakimon.sk.tsukuba.ac.jp> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1388783268 31460 80.91.229.3 (3 Jan 2014 21:07:48 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 3 Jan 2014 21:07:48 +0000 (UTC) Cc: esr@thyrsus.com, kfogel@red-bean.com, toby-dated-1389906911.cc0ede@dr-qubit.org, emacs-devel@gnu.org To: "Stephen J. Turnbull" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jan 03 22:07:53 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 1VzByC-0004GJ-SX for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 22:07:53 +0100 Original-Received: from localhost ([::1]:51816 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzByC-00058d-Ci for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 16:07:52 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55452) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzBy6-00058W-6G for emacs-devel@gnu.org; Fri, 03 Jan 2014 16:07:50 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VzBy1-0000dV-Ol for emacs-devel@gnu.org; Fri, 03 Jan 2014 16:07:46 -0500 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:60176) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VzBy1-0000dA-Ga for emacs-devel@gnu.org; Fri, 03 Jan 2014 16:07:41 -0500 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0MYU00700FQUIE00@a-mtaout22.012.net.il> for emacs-devel@gnu.org; Fri, 03 Jan 2014 23:07:40 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MYU0079VG0RIP10@a-mtaout22.012.net.il>; Fri, 03 Jan 2014 23:07:40 +0200 (IST) In-reply-to: <87fvp4kdoh.fsf@uwakimon.sk.tsukuba.ac.jp> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.172 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:167235 Archived-At: > From: "Stephen J. Turnbull" > Cc: Toby Cubitt , > esr@thyrsus.com, > kfogel@red-bean.com, > emacs-devel@gnu.org > Date: Sat, 04 Jan 2014 05:34:06 +0900 > > 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). > > 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? > Git is fundamentally different from bzr and hg, almost as different as > it is from CVS and RCS. Git is designed for use cases like "git > filter-branch", it's easy enough to implement it as a shell script > (though it would be slow), and probably it was prototyped that way > (although I would write the prototype in Lisp, not shell). I really > wouldn't want to try to do that in hg or bzr: although it could be > done, it would be unusably slow (because they don't have a separate > index, so the work has to be done in-tree-on-disk, rather than only on > metadata in memory). What does this have to do with clear and comprehensible documentation? > > Anyway, there's a big difference here: in Emacs documentation, > > every term is explained before it is used, and rarely used terms > > have cross-references to where they are described. > > I bet you can dip into any number of Info nodes where the terms > "buffer" and "window" are used without definition. I said "rarely used terms". Frequently used terms need to be understood in advance, by reading the preceding chapters. In any case, buffer and window can be intuitively understood, much more than "index" and "staging". > 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. > > > > Stores the current contents of the index in a new commit along with > > > > a log message from the user describing the changes. > > > > > > > > Huh? "Contents of the index"? I used to know what commit was, now I > > > > don't. > > 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. > > You are missing the point: I didn't want a tutorial. I use VCSes for > > many years, and dVCSes for some; I already know what it means to > > commit a changeset and what is the basic workflow of using a dVCS. > > But I think you've misstated the case here. Development has > workflows, and dVCS usage is adapted to them. It doesn't make sense > to talk about "*the* basic workflow of using a dVCS". You're actually > talking about *your* basic workflow, and how you use a dVCS in that > workflow. No, I'm talking about *the* basic workflow: make changes, then commit them. Tutorials seldom go beyond that. > > "Recording a commit"? what's that? And is "commit that has the exact > > same tree as its sole parent commit" a complicated way of saying "no > > changes since the last commit", or is there some important subtlety > > here that I'm missing? > > It's probably not important to you, so I won't go into detail, but > there are several subtleties that are missing from the simple > expression "no changes since the last commit". As there were a few subtleties missing from my mock description of C-f. > > --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. > > 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? Since that's what I will get, I want its documentation to be helpful. 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. 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.