Comments for Elijah's Blog http://blogs.gnome.org/newren Just another GNOME Blogs weblog Fri, 18 Jul 2008 21:31:59 +0000 http://wordpress.org/?v=2.3.3 Comment on That history meme by Jens Knutson http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-305 Jens Knutson Fri, 11 Apr 2008 08:46:57 +0000 http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-305 Thank god! I thought I was the only one who did that. Thank god! I thought I was the only one who did that.

]]> Comment on That history meme by anonim http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-304 anonim Fri, 11 Apr 2008 08:44:41 +0000 http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-304 me too me too

]]> Comment on That history meme by jdub http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-303 jdub Fri, 11 Apr 2008 07:01:35 +0000 http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-303 I am the same way. I think there's a little bit of OCD in it. I realised that my stats were so small because I have been (urk!) stuck in Windows and logging in to my laptop remotely. Kinda changes the way you use the command line. ;-) I am the same way. I think there’s a little bit of OCD in it. I realised that my stats were so small because I have been (urk!) stuck in Windows and logging in to my laptop remotely. Kinda changes the way you use the command line. ;-)

]]> Comment on That history meme by Alex http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-302 Alex Fri, 11 Apr 2008 04:30:16 +0000 http://blogs.gnome.org/newren/2008/04/11/that-history-meme/#comment-302 Thanks indirectly for the tip on CTRL-L! Thanks indirectly for the tip on CTRL-L!

]]> Comment on How NOT to write user-friendly documentation by Nikolaus http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-301 Nikolaus Tue, 08 Apr 2008 23:54:20 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-301 Terry: I think Knuth's documentation concept has a point. But this reminds me a personal anecdote: I remember that it was just that tutorial principle which drove me up the walls when I was reading Karl Marx's "Kapital". :-) He started with introducing very simple, basic ideas and claims, and it was quite obvious to me that these couldn't be true as stated. To be honest, I got angry about his flawed logic, just to find him fixing its defects and "telling the reader the truth" many, many pages later. :-) Terry: I think Knuth’s documentation concept has a point. But this reminds me a personal anecdote: I remember that it was just that tutorial principle which drove me up the walls when I was reading Karl Marx’s “Kapital”. :-) He started with introducing very simple, basic ideas and claims, and it was quite obvious to me that these couldn’t be true as stated. To be honest, I got angry about his flawed logic, just to find him fixing its defects and “telling the reader the truth” many, many pages later. :-)

]]> Comment on How NOT to write user-friendly documentation by Terry Cloth http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-300 Terry Cloth Sun, 06 Apr 2008 03:59:29 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-300 When trying to do documentation, it pays to remember Donald Knuth's comment: A [...] noteworthy characteristic of this manual is that it doesn't tell the truth. When certain concepts [...] are introduced informally, general rules will be stated; afterwards you will find that the rules aren't strictly true. [....] Once you understand a simple but false rule, it will not be hard to supplement that rule with its exceptions. -- D. Knuth, _The TeXbook_, pages vi--vii When trying to do documentation, it pays to remember Donald Knuth’s comment:

A […] noteworthy characteristic of this manual is
that it doesn’t tell the truth. When certain
concepts […] are introduced informally, general
rules will be stated; afterwards you will find that
the rules aren’t strictly true. [….] Once you
understand a simple but false rule, it will not be
hard to supplement that rule with its exceptions.

– D. Knuth, _The TeXbook_, pages vi–vii

]]> Comment on Many different kinds of revision specifiers by Jakub Narebski http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-297 Jakub Narebski Tue, 01 Apr 2008 11:11:58 +0000 http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-297 By the way, all graphical history viewers (gitk and qgit, probably also gitnub, gitview and giggle) show branches (heads) and tags markers along revision list (revision graph). Also, git-show-branch uses "transient" counting backwards from branches notation; unfortunately it is one of less known commands, and its output is a bit cryptic. It would be nice if git-log had switch which would function as if git-name-rev was specified as filter; the --decorate option only adds refs (heads and branches) markers in a way similar to gitk, qgit and gitweb. As to git-describe output: it looks (by default) like this: v1.5.5-rc2-1-ge95d75d, which means 1 commit since version tagged v1.5.5, with shortened sha1 being e95d75d (with 7 characters it should be unique in most repositories). The sha-1 is needed because with multiple branches there can be, and usually are, more than one commit (revision) can be 1 commit after given tag. As to being user-friendly... git still shows its origin as a bucnh of low level "plumbing" tools for hackers to use to build they own SCM scripts; it has much, much improved since. By the way, all graphical history viewers (gitk and qgit, probably also gitnub, gitview and giggle) show branches (heads) and tags markers along revision list (revision graph).

Also, git-show-branch uses “transient” counting backwards from branches notation; unfortunately it is one of less known commands, and its output is a bit cryptic. It would be nice if git-log had switch which would function as if git-name-rev was specified as filter; the –decorate option only adds refs (heads and branches) markers in a way similar to gitk, qgit and gitweb.

As to git-describe output: it looks (by default) like this: v1.5.5-rc2-1-ge95d75d, which means 1 commit since version tagged v1.5.5, with shortened sha1 being e95d75d (with 7 characters it should be unique in most repositories). The sha-1 is needed because with multiple branches there can be, and usually are, more than one commit (revision) can be 1 commit after given tag.

As to being user-friendly… git still shows its origin as a bucnh of low level “plumbing” tools for hackers to use to build they own SCM scripts; it has much, much improved since.

]]> Comment on Many different kinds of revision specifiers by Elijah http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-296 Elijah Tue, 01 Apr 2008 02:54:49 +0000 http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-296 Thomas: The leading one is just ugly legacy cruft, AFAICT. I don't know exactly how it came about, but it is technically possible to get a leading 2 or 3 or whatever. If you google on '"Assigning revisions" cederqvist' you'll find some links talking about how it's just convention and the -r option to cvs commit allows you to change the leading revision (though it apparently has some gotchas and I think I remember reading some people advising against it for various reasons). Another good read on the matter is http://www.eyrie.org/~eagle/notes/cvs/revisions.html. Havoc: I kind of like having cryptographic checksums around for unique identifiers (they seem cooler than bzr revid's, IMO); I just think an easily usable and manipulatable identifier is _also_ needed and that it should be just as prominent. I think hg had the right idea here, though I'd rather have something more meaningful and structural than simple 0...n. Gabriel: Thanks. :-) James: I modified the post to fix the mistake (changing a couple "revisions" to "revision numbers"); let me know if I still missed anything. I did specify that revids were unique in the original text; was I not clear enough? Thanks for pointing out the issues. tonfa: hg stores branch names under revision control too?!? Um, I guess that explains some comments I heard. Interesting; thanks for the explanation. Jakub: Cool, thanks for the pointer about git-describe. What does the shortened sha1 output by git-describe refer to? Also, I like how you put your numbering schemes comment; I should probably quote that in my post somewhere. Should I have said more about the commit descriptions in git? I'm quite familiar with the transiency issues and git-name-rev (see http://www.gnome.org/~newren/eg/git-eg-differences.html#log). In fact, I don't see the transience issue as a problem at all but a benefit (it makes it a lot easier to refer to "2 commits ago" than can be done in other systems where I first have to find out the current revision number) and it's really just an extension of the idea of hg and bzr to use easy-to-use revision numbers that are only valid locally. My issue with git here isn't that git doesn't have facilities for users to obtain useful information, it's that it doesn't bother helping users obtain it and learn the system. Personally, I don't think the --decorate option to git-log is all that useful (except maybe in special circumstances), and even the documentation for git-name-rev suggests a non-optimal use. But even if --decorate was generally useful or the example command in the git-name-rev doc was the optimal one, the problem is that git passes up one of the best opportunities to give users easily manipulatable versions, teach them revision specifiers, and give them a small picture of the structure of the commits. While I've railed on git for being user-hostile, I really have found that git is quite close to being a friendly system like the others; it really doesn't take that much to fix it up. A few small changes here and there (plus filling in a huge documentation gap) really does transform it from user-hostile to user-friendly. Thomas: The leading one is just ugly legacy cruft, AFAICT. I don’t know exactly how it came about, but it is technically possible to get a leading 2 or 3 or whatever. If you google on ‘”Assigning revisions” cederqvist’ you’ll find some links talking about how it’s just convention and the -r option to cvs commit allows you to change the leading revision (though it apparently has some gotchas and I think I remember reading some people advising against it for various reasons). Another good read on the matter is http://www.eyrie.org/~eagle/notes/cvs/revisions.html.

Havoc: I kind of like having cryptographic checksums around for unique identifiers (they seem cooler than bzr revid’s, IMO); I just think an easily usable and manipulatable identifier is _also_ needed and that it should be just as prominent. I think hg had the right idea here, though I’d rather have something more meaningful and structural than simple 0…n.

Gabriel: Thanks. :-)

James: I modified the post to fix the mistake (changing a couple “revisions” to “revision numbers”); let me know if I still missed anything. I did specify that revids were unique in the original text; was I not clear enough? Thanks for pointing out the issues.

tonfa: hg stores branch names under revision control too?!? Um, I guess that explains some comments I heard. Interesting; thanks for the explanation.

Jakub:

Cool, thanks for the pointer about git-describe. What does the shortened sha1 output by git-describe refer to? Also, I like how you put your numbering schemes comment; I should probably quote that in my post somewhere.

Should I have said more about the commit descriptions in git? I’m quite familiar with the transiency issues and git-name-rev (see http://www.gnome.org/~newren/eg/git-eg-differences.html#log). In fact, I don’t see the transience issue as a problem at all but a benefit (it makes it a lot easier to refer to “2 commits ago” than can be done in other systems where I first have to find out the current revision number) and it’s really just an extension of the idea of hg and bzr to use easy-to-use revision numbers that are only valid locally.

My issue with git here isn’t that git doesn’t have facilities for users to obtain useful information, it’s that it doesn’t bother helping users obtain it and learn the system. Personally, I don’t think the –decorate option to git-log is all that useful (except maybe in special circumstances), and even the documentation for git-name-rev suggests a non-optimal use. But even if –decorate was generally useful or the example command in the git-name-rev doc was the optimal one, the problem is that git passes up one of the best opportunities to give users easily manipulatable versions, teach them revision specifiers, and give them a small picture of the structure of the commits. While I’ve railed on git for being user-hostile, I really have found that git is quite close to being a friendly system like the others; it really doesn’t take that much to fix it up. A few small changes here and there (plus filling in a huge documentation gap) really does transform it from user-hostile to user-friendly.

]]> Comment on Many different kinds of revision specifiers by bronson http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-295 bronson Mon, 31 Mar 2008 17:28:46 +0000 http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-295 Havoc, I disagree. Right now Git uses 4 bits/char = 40 chars. Even if you could encode 6 bits/char (base64), you'd still have a 28 character identifier. That's still too long to type by hand. So, I don't see any reason to introduce all the additional complexity of some sort of custom textual encoding. Either way, the sha1 is unreadable and you'll never type more than the first 5 chars of it. Havoc, I disagree. Right now Git uses 4 bits/char = 40 chars. Even if you could encode 6 bits/char (base64), you’d still have a 28 character identifier. That’s still too long to type by hand.

So, I don’t see any reason to introduce all the additional complexity of some sort of custom textual encoding. Either way, the sha1 is unreadable and you’ll never type more than the first 5 chars of it.

]]> Comment on Many different kinds of revision specifiers by Jakub Narebski http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-294 Jakub Narebski Mon, 31 Mar 2008 15:42:25 +0000 http://blogs.gnome.org/newren/2008/03/31/many-different-kinds-of-revision-specifiers/#comment-294 First, descriptions of commits counting from branch tips backwards (e.g. HEAD^, or HEAD~5, or master~10^2~12) are transient; only those using tags are constant, but not all revisions have such description. Second, you can get them in git-log output using git-name-rev as filter (see documentation), or --decorate option to git-log. BTW. there is yet another way to refer to revision (besides shortened sha-1), namely this returned by git-describe, in the form of closest tag + forward counting + shotened sha-1. Note also that all numbering schemes either need central numbering authority (which repository we take those numbers from), or have to be local for a repository. First, descriptions of commits counting from branch tips backwards (e.g. HEAD^, or HEAD~5, or master~10^2~12) are transient; only those using tags are constant, but not all revisions have such description. Second, you can get them in git-log output using git-name-rev as filter (see documentation), or –decorate option to git-log.

BTW. there is yet another way to refer to revision (besides shortened sha-1), namely this returned by git-describe, in the form of closest tag + forward counting + shotened sha-1.

Note also that all numbering schemes either need central numbering authority (which repository we take those numbers from), or have to be local for a repository.

]]>