Hyperlinks in *vc-change-log*

Hyperlinks in *vc-change-log*

[Phil Hagelberg]

I've written up some code that I find quite useful for working with
VC. The code below adds buttons to each commit entry in *vc-change-log*
buffers, essentially making them hyperlinks to the revision mentioned
using vc-find-revision.

I think with a bit of work this could be incorporated into Emacs if
people think it would be useful and appropriate. There are a few caveats
first:

* The button actions use closures and thus require the cl library. As I
  understand it, this dependency would have to be removed for it to be
  included in Emacs. I consider this to be somewhat disappointing as it
  will add complexity to the code, but I respect this choice of the
  maintainers.

* It only supports three VC backends: SVN, CVS, and Git. This is simply
  because I don't have much experience with other VC systems; it would
  be trivial to add support for more by adding appropriate entries to
  vc-button-regexp-alist to match what a commit looks like in each
  backend.

* Right now it only works with *vc-change-log* buffers that correspond
  to a single file. I am not sure what the action makes sense for
  buffers that correspond to a fileset; I have mostly used VC logs in
  the context of single files.

* It currently uses hooks. If it were incorporated into Emacs, it could
  probably be added directly to an existing function.

Anyhow, the code is included below. Feedback would be appreciated. I've
tested it in Emacs built from a week or two ago with Git, CVS, and SVN
projects, but I'm sure it could benefit from more testing and feedback.
Even if it is not incorporated into Emacs, I think it's useful on its own.

Thanks,
Phil Hagelberg
http://technomancy.us

(require 'cl)

(defvar vc-button-regexp-alist
  '((Git . "^commit +\\([0-9a-f]\\{40\\}\\)$")
    (SVN . "^r\\([0-9]+\\) ")
    (CVS . "revision \\([0-9]+.[0-9]+\\)"))
  "An alist pairing VC backends to regexps describing what commits look like.")

(defun vc-log-make-buttons ()
  "Make each reference to a commit in the current buffer act as a hyperlink."
  (let* ((buffer-read-only nil)
	 (file (buffer-file-name vc-parent-buffer))
	 (button-regexp (assocref (vc-backend (list file)) vc-button-regexp-alist)))
    (save-excursion
      (beginning-of-buffer)
      (while (search-forward-regexp button-regexp nil t)
	(lexical-let ((cl-file file) ;; closure time!
		      (revision (match-string 1)))
	  (make-text-button (match-beginning 1) (match-end 1)
			    'action (lambda (arg) (interactive)
				      (switch-to-buffer
				       (vc-find-revision cl-file
							 revision)))))))))

(add-hook 'log-view-mode-hook 'vc-log-make-buttons)

Re: Hyperlinks in *vc-change-log*

[Lennart Borgman (gmail)]

Phil Hagelberg wrote:
> * The button actions use closures and thus require the cl library. As I
>   understand it, this dependency would have to be removed for it to be
>   included in Emacs. I consider this to be somewhat disappointing as it
>   will add complexity to the code, but I respect this choice of the
>   maintainers.


I think it is ok to use

   (eval-when-compile (require 'cl))

See

   (info "(elisp) Coding Conventions")

Re: Hyperlinks in *vc-change-log*

[Stefan Monnier]

> I've written up some code that I find quite useful for working with
> VC. The code below adds buttons to each commit entry in *vc-change-log*
> buffers, essentially making them hyperlinks to the revision mentioned
> using vc-find-revision.

Doesn't seem like a bad idea.  But it should be generalized to show not
only files but also diffs.

> * The button actions use closures and thus require the cl library. As I
>   understand it, this dependency would have to be removed for it to be
>   included in Emacs. I consider this to be somewhat disappointing as it
>   will add complexity to the code, but I respect this choice of the
>   maintainers.

Not a problem, you misunderstood the requirement.

> * It only supports three VC backends: SVN, CVS, and Git. This is simply
>   because I don't have much experience with other VC systems; it would
>   be trivial to add support for more by adding appropriate entries to
>   vc-button-regexp-alist to match what a commit looks like in each
>   backend.

The code should not be thought of as a feature of VC but of log-view.el.

> * Right now it only works with *vc-change-log* buffers that correspond
>   to a single file. I am not sure what the action makes sense for
>   buffers that correspond to a fileset; I have mostly used VC logs in
>   the context of single files.

For multifile logs, the best option would be to popup a menu of files.
BTW this is specific to the display of files.  For `diffs', this problem
wouldn't occur.  

> * It currently uses hooks. If it were incorporated into Emacs, it could
>   probably be added directly to an existing function.

Yes, it should probably be merged directly into log-view's font-lock
regexps or something like that.


        Stefan

Re: Hyperlinks in *vc-change-log*

[Dan Nicolaescu]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

  > > * It currently uses hooks. If it were incorporated into Emacs, it could
  > >   probably be added directly to an existing function.
  > 
  > Yes, it should probably be merged directly into log-view's font-lock
  > regexps or something like that.

Also please note that VC backends use define-derived-mode to derive
modes from log-view.  That's probably the right place to update the
font-lock regexps.

Re: Hyperlinks in *vc-change-log*

[Phil Hagelberg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I've written up some code that I find quite useful for working with
>> VC. The code below adds buttons to each commit entry in *vc-change-log*
>> buffers, essentially making them hyperlinks to the revision mentioned
>> using vc-find-revision.
>
> Doesn't seem like a bad idea.  But it should be generalized to show not
> only files but also diffs.

I'm not sure what you mean by this. When I follow a hyperlink labelled
with a given commit ID, I would expect to see the file revision of the
file as it was in that commit.

I'm guessing this means that it would also be handy to be able to see a
diff between the given revision and the previous one, or perhaps the
given revision and the current one. But I'm not sure how that would work
in terms of the UI. This is all implemented using buttons, so I am only
tying functionality to text that already exists in the buffer. Perhaps
another binding could be used? RET to visit a revision, and C-RET to
view the diff between that revision and the last?

>> * The button actions use closures and thus require the cl library. As I
>>   understand it, this dependency would have to be removed for it to be
>>   included in Emacs. I consider this to be somewhat disappointing as it
>>   will add complexity to the code, but I respect this choice of the
>>   maintainers.
>
> Not a problem, you misunderstood the requirement.

That's great; I love having closures available. I still might have a few
things in there that need cl at runtime, but biggest thing is the
lexical-let.

> For multifile logs, the best option would be to popup a menu of files.
> BTW this is specific to the display of files.  For `diffs', this problem
> wouldn't occur.  

That makes perfect sense; good idea. I would expect a keyboard
invocation of the hyperlink would cause the choice to be given in the
minibuffer, while a mouse invocation would cause a contextual menu much
like the one you see with C-mouse-1. Is there any way to create such a
menu in a unified fashion? I am only familiar with the minibuffer route.

-Phil
http://technomancy.us

Re: Hyperlinks in *vc-change-log*

[Stefan Monnier]

>> Doesn't seem like a bad idea.  But it should be generalized to show not
>> only files but also diffs.

> I'm not sure what you mean by this. When I follow a hyperlink labelled
> with a given commit ID, I would expect to see the file revision of the
> file as it was in that commit.

Depends on your point of view: some people/VCS consider each "id" as
referring to a particular revision, others consider it as referring to
a particular changeset (i.e. patch/diff).  While most VCS take one point
of view as "fundamental", they all provide ways to get the other view.

> I'm guessing this means that it would also be handy to be able to see a
> diff between the given revision and the previous one,

Yes.

> or perhaps the given revision and the current one.

We could add that as well.

> But I'm not sure how that would work in terms of the UI.  This is all
> implemented using buttons, so I am only tying functionality to text
> that already exists in the buffer.  Perhaps another binding could be
> used?  RET to visit a revision, and C-RET to view the diff between that
> revision and the last?

I was thinking of a menu.  From the keyboard we already have bindings
for those operations, IIRC (at least `d' for the diff).

>> For multifile logs, the best option would be to popup a menu of files.
>> BTW this is specific to the display of files.  For `diffs', this problem
>> wouldn't occur.  

> That makes perfect sense; good idea. I would expect a keyboard
> invocation of the hyperlink would cause the choice to be given in the
> minibuffer, while a mouse invocation would cause a contextual menu much
> like the one you see with C-mouse-1. Is there any way to create such a
> menu in a unified fashion? I am only familiar with the minibuffer route.

I don't think we do exactly, but we have code that does that in various
places: tmm-menubar and imenu.el at least.  You may want to steal some
of their code and (better yet) merge that code into a generic function
that we could install in subr.el or somesuch.


        Stefan

Re: Hyperlinks in *vc-change-log*

[Phil Hagelberg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> But I'm not sure how that would work in terms of the UI.  This is all
>> implemented using buttons, so I am only tying functionality to text
>> that already exists in the buffer.  Perhaps another binding could be
>> used?  RET to visit a revision, and C-RET to view the diff between that
>> revision and the last?
>
> I was thinking of a menu.  From the keyboard we already have bindings
> for those operations, IIRC (at least `d' for the diff).

I actually realized that the whole of what I wanted when I wrote that
code is already present in log-view.el. I just assumed that RET would be
the binding for visiting the revision under the point, but it's actually
bound to 'f'. I'd suggest that RET be bound to log-view-find-revision in
log-view-mode. This just seems much more obvious to me.

> For multifile logs, the best option would be to popup a menu of files.
> BTW this is specific to the display of files.  For `diffs', this problem
> wouldn't occur.  

It turns out the current implementation of log-view-diff only diffs one
file in the fileset, so this could be fixed. In addition giving a menu
in the minibuffer for log-view-find-revision on filesets seems like a
good idea. I will work on implementing these.

-Phil

http://technomancy.us

Re: Hyperlinks in *vc-change-log*

[Thien-Thi Nguyen]

() Phil Hagelberg <phil@hagelb.org>
() Thu, 10 Apr 2008 22:48:27 -0700

   That's great; I love having closures available.

A button can store state, not only the text it is attached
to (see `button-label'), but other stuff as well.

Here, you don't even need that.  Probably this suffices:

(defun log-view-find-revision-at-button (button)
  (log-view-find-revision (button-start button)))

(make-text-button BEG END
  'action 'log-view-find-revision-at-button)

thi

Re: Hyperlinks in *vc-change-log*

[Juri Linkov]

> I'm guessing this means that it would also be handy to be able to see a
> diff between the given revision and the previous one, or perhaps the
> given revision and the current one. But I'm not sure how that would work
> in terms of the UI.

A good UI with links would be like used by Web interfaces to VCS repos, e.g.
http://cvs.sv.gnu.org/viewvc/emacs/lisp/vc.el?root=emacs&sortby=date&view=log

Here we have links to view, annotate, diff to previous, etc.

-- 
Juri Linkov
http://www.jurta.org/emacs/