A more friendly way of viewing history for a single file or directory

Jean-Luc's Avatar


29 Mar, 2011 12:45 PM


First of all, thanks for delivery MacHg. It's a really great UI for SCM and it was one major reason for which I chose Mercurial for my software projects.

However there is a feature that - for my usage - is really missing: a user-friendly way of seeing the history graph of a single file or of all files in a given directory. This could be done via a kind of mix between a file browser and the existing history view.

Or course there is the way described in the FAQ as "How do I view the update history for a single file?", but frankly, typing file names is an error-prone task and It would be great to have a better tool for this feature.



  1. Support Staff 1 Posted by jason on 31 Mar, 2011 12:43 AM

    jason's Avatar

    First thanks for the praise about MacHg! Its always nice to hear and never gets old! :)

    Second, yes I can definitely understand the request. I have wanted such a thing myself on a good number of occasions. The question is what would be the right way to expose the capability? In the end as things stand now it would be a matter of getting the file name or directory name into the search field and switching to the history view... But is that enough. I can imagine a menu item maybe? Or some double click on the link with some key combination, but this might be cluttering the interface a bit. Coda sort of allows this in their sidebar... but I haven't seen much else like it...

    Did you have some concrete ideas in my of what the "combined" file browser / history view might look like... I am not saying I will of course implement this but it would be interesting for me to see something mocked up in say photoshop or IB if you have ideas, or maybe just a description... I always like to see fresh ideas and regularly "steal" inspiration from other programs / suggestions :)


  2. 2 Posted by Jean-Luc Jumper... on 31 Mar, 2011 12:54 PM

    Jean-Luc Jumpertz's Avatar

    Hi Jason,

    Thanks for your answer.

    Here is a UI proposal for this feature. My working assumptions were:
    - try to make it consistent with the current design choices in MacHg,
    - try to make it simple enough, basing it on similar-to-existing views, hopping that you can implement it mostly by reusing existing code.

    The basic idea would be to add an history panel in the file browser view, in the lower part of the window. A (toolbar?) button would permit to toggle the display of this panel on or off.
    This history panel would display only revisions where one of the selected files in the browse panel has changed, with the corresponding graphic subtree (this graph would really be appreciated, if not too complicate to build...).
    Selecting 2 revisions in this view and clicking the diff button would display the diffs of each selected files between the chosen versions; in a similar way, selecting 1 revision in the tree and clicking diff would display the diff of selected files between the chosen revision and the previous one.

    I tried to put this layout proposal in the attached PNG file.

    Hope this helps.
    Of course, I will fully understand if you do it another way or don't do it at all. :-)


  3. Support Staff 3 Posted by jason on 31 Mar, 2011 04:41 PM

    jason's Avatar

    Interesting! Can you actually email the picture directly to me at jason at jasonfharris.com? Tender is scaling the image down a lot.

    Couple of points:
    The thing is with the nice history graph you have there we can't nicely do for just a single file in an incremental way. You would have to parse the whole history graph to be able to do this. Right now MacHg works in an incremental way and thats why its fast when working with repositories with some 300,000 commits. If you needed to parse all of those 300,000 commits things would get much slower. There is the debugdag command in mercurial but...

    Actually, this would be something that would need to work for the history view with searches in any case... It would be quite nice if this worked. (Right now in the history view if you search on a specific term you can note that the graph simply disappears... This would need to change and it would be a lot of work. Actually it might best be done in Mercurial proper...)

    Second the screen would get pretty crowded since we are basically putting the history together with the file browser... This is moving to something a bit more like tortoiseHg and is very pc like. On the Pc you see this kind of interface a lot more. Ie "Ohh we need to have the search history visible... and we need the project settings... and opps, we need the results showing... and yeah we should really show the input... and yep lets show this chooser, and ..." where in the end you are working in a squashed up rectangle of the screen for the main thing you actually want to work on... (You see this a lot in people who work on visual studio on windows. It never ceases to amaze me that some of my friends / colleagues who work in windows development end up working in a small maybe 40% size of their screen window to actually look at the code. The rest is just clutter around their code window. Mind blowing...) But of course something like this sort of needs to happen when you have show directly linked simultaneous information... see this blog post for some thoughts on this with respect to show inapplication-diffs.

    Maybe a nice graphic cross fade and zoom would take one from the files view to the history view... Hmmm...

    (So while I am on the topic of space and use of space with the GUI design... I have to say of course the sidebar is standard in macintosh applications, and so it is in MacHg. However I would like to be able to hide it, but I currently use the bottom left corner for status and progress. I am thinking about how I could actually get around this... I am also thinking about how I could hide the rhs bar in the files view in order to save more space... etc. So I think about layouts a lot...)

    BTW what is your main use case for having both the history view and the files view together at the same time. (I have wanted this myself but maybe for different reasons than others...)

    In any case thank you for the thought provoking suggestion!


  4. 4 Posted by Jean-Luc Jumper... on 31 Mar, 2011 05:40 PM

    Jean-Luc Jumpertz's Avatar

    I think there is a basic misunderstanding of my previous message, or a lack of clarity on my side, so let me rephrase it differently.

    The interface that I am proposing is nothing more than the currently existing "Differences view" but with a reverse perspective: instead of selecting the revisions first, and then navigate in the file browser, just put the thing upside down by selecting a file and then navigation inside its revisions.
    This doesn't make the screen more crowded nor PC like, I think. And doesn't change anything to the sidebar. :-)

    Regarding the version graph for a single file, I can understand the cost of implementing it in a large repository and agree with you that "Actually it might best be done in Mercurial proper..."
    Too bad ! Having the possibility to visualize the version tree of individual files and to see easily branch and merge points at the file's level proved to be an invaluable tool when integrating and debugging big software projects.
    I used this kind of tools for years (with big SCM systems like ClearCase) and I really miss the file-level history now that I am developping Mac/iOS software.

    The use case I have in mind is the following:
    for a given file, get an overview of its history with the associated revision numbers or associated labels, with an easy way of identifying the branches and merge, and with a simple way of comparing any 2 versions of this file's history.



  5. Support Staff 5 Posted by jason on 31 Mar, 2011 06:35 PM

    jason's Avatar

    Interesting... Maybe then this should be part of my planned annotation view... Of course the annotation view was going to look at individual files and not really all the files in the directory... Would that satisfy your needs, or do you really want to be able to do this on a directory level?

    Also one thing about the "select a file and then view the history" is that regrettably files are temporal. Ie at some past or future revision the file might not be present or it might be renamed and moved. So you can only give a list of files as of a snapshot. you could of course just list all files that have ever been in the repository at any stage... But that might be quite confusing if renames and such have happened... I have thought about this a bit...

    (Also just to clarify, I am not so much worried about looking PC like, more I am worried about screen real estate... But it just so happens that coincidentally lots of PC programs get the screen real estate balance really wrong... :) )

    I will let all of this tick over in the back of my mind though....

    Thanks again for the interesting thoughts here though. I'll see what I can do in some future version to do something in the annotation view so that the history is available like this...


  6. 6 Posted by Jean-Luc Jumper... on 31 Mar, 2011 08:25 PM

    Jean-Luc Jumpertz's Avatar

    >> Of course the annotation view was going to look at individual files and not really all the files in the directory... Would that satisfy your needs, or do you really want to be able to do this on a directory level?

    Individual files would really be fine: that would satisfy most of my needs.
    History for a whole directory or a group of files is only a plus, as it can make relationships between changes in related files easier to trace.

    By the way, regarding the renaming of files, does Mercurial keep track of it -if declared properly ? It seems to me that, after remaning a file with MacHg (menu Action>RenameAnItem...) the renaming appears appears as separate remove and add files (at least it is described so in the revision info).
    If there is no proper tracking of file renaming in mercurial, I agree that file history would lose a significant part of its value. :(



  7. Support Staff 7 Posted by jason on 31 Mar, 2011 11:43 PM

    jason's Avatar

    Thanks! It will definitely be a lot simpler in the interface if its file by file...

    MacHg uses 'hg rename', and happily this is properly tracked. To see the renames you need to do

    hg log --follow ...

    MacHg doesn't do any special tracking on top of this so you can see eg

    foobar.txt (formally fish.txt)

    Or something similar...


  8. 8 Posted by Jean-Luc Jumper... on 01 Apr, 2011 08:10 AM

    Jean-Luc Jumpertz's Avatar

    >> MacHg uses 'hg rename', and happily this is properly tracked. To see the renames you need to do hg log --follow ...

    Thanks. I checked a few renamed files with the "hg log --follow" command and they were properly tracked, even if this doesn't appear in the history view.

    This can bring some worries for the user (type of "was my rename command really effective ?") but this is not an issue per se.
    However I didn't find the way in MacHg to compare a renamed file with its previous version: clicking on the renamed file (marked as added) just compared it with /dev/null in FileMerge.
    Maybe a possible improvement in a future version? :)

    And to end up, here are 2 more ideas for easier file management in MacHg:
    - add the possibility to directly rename à file in the file browser by clicking on its name or by dragging it to a different directory (directly using hg rename),
    - add a duplicate command (or option-drag) on the selected file, that would use hg copy

    A common renaming use case (at least for me) is to rename files in the current IDE (e.g. in XCode) first and then switch to MacHg to take into account that rename in Mercurial.
    In this configuration, we can see in MacHg one missing file + an untracked file, and it would be great if the dragging a missing file onto an untracked file just automatically could cause the hg rename of this file. (hope it's clear :)



  9. Support Staff 9 Posted by jason on 01 Apr, 2011 09:24 AM

    jason's Avatar

    You can just do menu Action > AddRemove and it will automatically do the rename if the files are similar enough. (If you haven't touched the file then its 100% similar.) If the file rename wasn't detected then you can simply up the similarity. See the preferences item in MacHg preferences > Mercurial.

    But as for your suggestion of file drag to do the rename, I think I can understand that... Go ahead and create an account and file it as an enhancement at: https://bitbucket.org/jfh/machg/issues. I don't know if users will ever discover it though :)...

    rename by clicking on the file I am not so keen on. Renaming is a operation which one doesn't want to discourage, but as you can see working with renamed files isn't always smooth. eg across diffs, merges, transplants, rebases, etc. renamed files could be a problem. (It would be better if this were not the case of course...) In any case its pretty easy to rename using the menu item, or the contextual menu item... If enough people really want to rename things through direct manipulation I will of course reconsider.

    BTW your note of the fact that MacHg doesn't display the diff correctly and just compares to /dev/null when diffing renamed files is definitely a bug. Happily its not my bug :) I filed this in the mercurial bugs as issue 2744.

    Thanks again for your helpful comments!


  10. 10 Posted by Jean-Luc Jumper... on 01 Apr, 2011 09:45 AM

    Jean-Luc Jumpertz's Avatar

    Thanks for the tip with the addremove command. I just didn't get the subtlety of what the --similarity option was about.
    I guess it will handle just fine most, if not all, of my renaming needs. :)

  11. Support Staff 11 Posted by jason on 03 Oct, 2011 01:07 AM

    jason's Avatar

    Closing as answered! :)

  12. jason closed this discussion on 03 Oct, 2011 01:07 AM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac