UI issues with git integration


#1

I had never used git but I downloaded git for Windows just to experiment with it within Diffplug. I’m impressed with the integration. I’m currently experimenting with using it as a sort of intermediate layer between my working files and our official VCS (StarTeam). I can maintain a breadcrumb trail as I develop new features or fixes locally and use the DiffPlug integration to browse through them before I do ‘official’ check-ins to StarTeam.

Anyway, on to the real subject (the UI for DiffPlug git integration).

It took me quite a bit of fumbling around to finally find the UI in which Ned starts out his git integration video demos. I think it was a right click>Browse and then a right click>Show history – but I still am not comfortable finding that easily. This definitely needs some refinement to make it MUCH more discoverable.

Also, once you find that page, the pane that is used for commit messages has no title, label, or anything else to indicate what it is for. I don’t even remember how I figured out what it is for.

I also think that the obscurely placed ‘Reflog’ and ‘Sync’ buttons, since they completely change the view, should have more prominence (probably at the top of the subwindow/tab) and they should probably have better names (or at least tooltips or something to explain what they do).

I’ve managed to stumble my way through to getting this to do some pretty neat stuff but it wasn’t even close to intuitive. I don’t think that much of my problem was due to being a git novice as I haven’t tried to do anything sophisticated.

Anyway, I’m quite impressed with the potential for this and am looking forward to the improvements that I have no doubt will be forthcoming.


#2

Thanks very much for this feedback, Les! Sorry for the delayed response - I had misconfigured this new forum so I didn’t get a notification of your post. Fixed now!

As soon as we released, we began working on a detailed manual which addresses some of these issues. Writing the manual has been an instructive review process - in some places we had a hard time writing the manual, because the software itself was hard to use. The next version has some significant usability improvements.

I also think that the obscurely placed ‘Reflog’ and ‘Sync’ buttons, since they completely change the view, should have more prominence

This was a particularly helpful chunk! I thought that our current snapshot was ready to release, but after reading this, I think there are low-hanging fruit in this area that we should pick up first. I’ll post further info to this thread when it is available.


#3

Thanks for the response, Ned.

I’m glad to hear that you are working on documentation and usability enhancements.

Keep up the good work.

BTW:

  • FYI: I did get an e-mail notification for your post.
  • I’m a bit surprised/disappointed that your forum is getting nearly no traffic. Hopefully that will change in the future. I think that a forum is a great idea. One of my favorites is the forum for the SlickEdit editor (don’t know if you are familiar with SlickEdit, but for me it is an indispensable tool, and the forum shows me ways to make it even more useful). Beyond Compare has a nice forum as well. There seems to be a strong correlation between really solid, useful tools and a helpful user community that uses those tools. Nice to see that you’ve taken the first step in joining those ranks. Also, your forum UI is quite nice.

Best regards,
Les


#4

There seems to be a strong correlation between really solid, useful tools and a helpful user community that uses those tools. Nice to see that you’ve taken the first step in joining those ranks.

Thanks Les! We’ve got a lot of work to do moving some of the knowledgebase that’s locked up in customer support emails to this forum. Most of our Simulink customers have strict policies about their employees using forums, but we’re working to get some of that removed.

I also think that the obscurely placed ‘Reflog’ and ‘Sync’ buttons, since they completely change the view, should have more prominence (probably at the top of the subwindow/tab)

Here’s a screenshot from 1.6.2, released last night:

We put them at the bottom instead of the top to save screen space.

tooltips or something to explain what they do

We’re working on a bunch of stuff to help with training, to be shipped in 1.6.3.


#5

Nice work on the 1.6.2 update. Putting Sync and Reflog on tabs (with ‘Preview’ on a separate tab when active) makes a lot more sense.

The ‘commit comments’ field is still unlabeled. Having previous comments there now gives a bit of a clue, but only if you have used it before - at which point you must have figured out what it is. Suggestion: if you don’t want to “waste” space by putting an external label on this field, you could, perhaps, put default text in it that says something like “Enter commit comments here”. I know this would require extra logic to prevent actually entering this default text as a commit comment. To me it seems like giving up one line to add a label outside the field would be more obvious and require less logic in your code.

I know that you are concentrating on the git integration but I still think that you might want to think about a way to expose this more clearly on the top level interface of DiffPlug. It still takes several non-intuitive steps to get to the really useful git integration view.

Also, what is “Tips”? I’m guessing it must have to do with branches - which I haven’t experimented with yet.

Best regards,
Les


#6

Another suggestion (or two) about the ‘commit comments’ field.

The current implementation appears to have this field filled in with the last comment. If you don’t want to use that comment, it takes deliberate actions to select the existing comment and overwrite it with the new comment.

You might consider a listbox at the top, or some other way of recalling previous comments (only if the user wants to) rather than defaulting to the previous comment and requiring extra effort to delete and replace with a new comment.

I still think you should label this field prominently. Give up one line of text above it so that users know what it is for.


#7

put default text in it that says something like “Enter commit comments here”.

We started working on this, but didn’t get it working in time for 1.6.3.

You might consider a listbox at the top, or some other way of recalling previous comments

This might have convinced me to allocate a line, so that we can implement this feature. As always, thanks for the feedback Les. We’re listening!


#8

Sorry for the long delay! We’ve been working hard on a big new feature to improve documenting Simulink models, so the git client has slowed down a little bit. Starting in 1.6.3 (released today), the git client has these quickstart screens:

We’ve also started to write a git tutorial called “Git from scratch”. It’s not finished yet, but a first draft is up.


#9

Very nice!

A bit step forward in explaining the git integration more clearly.

What is the ‘big new feature to improve documenting Simulink models’? Maybe you can’t say right now. It doesn’t appear to be included in 1.6.3.

Keep up the good work.

Regards,
Les


#10

Are you still considering putting an MRU listbox on the commit comment field? Or at least a label?

I think that would be useful, though it may be because of the way I use source control. I still tend to think of a source control tool in terms of managing/tracking changes to individual files. I’ve read that this is NOT the philosophy of git. For some of us, I think that “files don’t matter” is counter-intuitive. I tend to do file check-ins one at a time (and sometimes using the same check-in comment). If I did check-ins one ‘feature’ at a time for multiple files, things might be different.


#11

What is the ‘big new feature to improve documenting Simulink models’? Maybe you can’t say right now. It doesn’t appear to be included in 1.6.3.

Yup, not shipping until 1.7.0 (really crunching to get it out, hopefully very soon). It’s a mechanism for writing word documents which reference Simulink diagrams and blocks directly. No more copy-pasting images that go stale - it’s a live reference to the actual model. To be followed shortly by Word document diffing.

I tend to do file check-ins one at a time (and sometimes using the same check-in comment)

Here’s an argument against this practice: let’s say I move a function from file A to file B. If I commit them one at a time, it looks like I deleted a function and then added it, but if I commit them together it’s clear that I moved it. In a perfect world, every published commit (as distinct from personal checkpoint commits) is a working piece of software, and that’s only possible if commits are atomic across the entire file tree.

Are you still considering putting an MRU listbox on the commit comment field?

I think this is only useful if you’re following the commit-per-file practice. You should use the tool however it’s useful to you, but I don’t think commit-per-file is the best way to use it, so I don’t plan to implement this feature. I would like to make it easier to retrieve commit messages which weren’t committed, but I think that if a message is committed, it’s unlikely to need to be committed again. In the rare case that it is, it’s easy enough to copy-paste.

I see this is as low-priority, and when it does get implemented, I don’t think it will do what you want re: committing files one at a time.

Or at least a label?

I think the new documentation, which opens very loudly for new users, is sufficient. I’d like to implement the “type commits here” suggestion, but it’s low priority.


#12

The upcoming 1.7.0 feature sounds really interesting! Looking forward to it.

I definitely understand the point about commits being atomic (self-consistent) and therefore not being done on a per-file basis for a lot of use cases (e.g., a codebase that compiles into a single working product). This is especially true, as you say, for ‘published’ commits when others are working on the same ‘project’.

My current use case is a bit different. I’m working on a set of loosely coupled Matlab scripts/functions and using git for what you aptly describe as ‘personal checkpoint commits’. The ‘loose coupling’ of this ‘project’ means that I can incorporate features/changes to files much more independently. As a trivial example, I might do check-ins for different files at different times where the commit comment is simply “Format clean-up”. This is the type of scenario where I thought the MRU list of commit comments might come in handy.

I’m now beginning to see that this would be of limited usefulness and not worth the trouble to implement. Especially since, as you point out, I can simply find a commit with the desired comment in the History and copy/paste it for a new commit. This is probably just as easy to do (if not more so) as my idea of the MRU list (actually it isn’t my idea – TortoiseCVS had this).

I’m not sure what you mean about retrieving commit messages which weren’t committed. Is there such a thing?

I agree that the new documentation (Help tab) is a giant step forward for helping new users understand the interface.

Thanks again. Happy Thanksgiving!

Les