Iceberg goodness plus ideas

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Iceberg goodness plus ideas

Ben Coman
First, kudos to Iceberg team for detecting the mistake I made messing
around at the command line under the feet of an Iceberg managed repo.
I'm interested in some general discussion of a few ideas before logging any issues.

I had an Iceberg managed repo branch "ready-multiple-commands"
as shown at [A] in the attached pic.
(note that this is "exercism/pharo" not "pharo-project/pharo")
  
I wanted to compare "git log --graph" between a few branches
so I jumped into a command prompt and did so.  Along the way I changed 
branch to "master" from the command line [B].
Then friends arrived and it was six hours until I got back to it
and was presented with "Detached Working Copy" [C],
and I'd forgotten what I'd done.  

Repair repository [D] didn't make this immediately obvious 
although given the two commits after a while I managed to work it out
and simply `git checkout ready-multiple-commands` at the command line
fixed things, returning the display to [A].

So the discussion points I'm interested in are:

a. An extra column "Image Branch" with the existing column 
renamed "Disk Branch" would have made my mistake immediately obvious.

b. Such under the covers command line operation may be a corner case(??),
so if not an extra column, a red Status message "Image Branch ready-multiple-commands" or similar would have helped.

c. In the first paragraph of [D] it was not apparent what "working copy" and "repository commit" referred to (although after a while I worked it out from the given commit hashes -- the former was in-Image and the latter on-disk.  But the files on disk are a "working copy" in all other git documentation and it invites confusion not to refer to it like that.  It seems to me we deal with two working copies: an "image working copy" and a "disk working copy". That terminology would have eased discovery of my mistake.

d. Instead of the commit hashes [D], is it feasible to match those to branches/tags and display those.  That would have made my mistake more obvious.

d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

cheers -ben
Reply | Threaded
Open this post in threaded view
|

Re: Iceberg goodness plus ideas

Ben Coman
I found a related issue https://github.com/pharo-vcs/iceberg/issues/762
and attached there the pic I left off the previous post.

cheers -ben

On Sun, 9 Sep 2018 at 23:06, Ben Coman <[hidden email]> wrote:
First, kudos to Iceberg team for detecting the mistake I made messing
around at the command line under the feet of an Iceberg managed repo.
I'm interested in some general discussion of a few ideas before logging any issues.

I had an Iceberg managed repo branch "ready-multiple-commands"
as shown at [A] in the attached pic.
(note that this is "exercism/pharo" not "pharo-project/pharo")
  
I wanted to compare "git log --graph" between a few branches
so I jumped into a command prompt and did so.  Along the way I changed 
branch to "master" from the command line [B].
Then friends arrived and it was six hours until I got back to it
and was presented with "Detached Working Copy" [C],
and I'd forgotten what I'd done.  

Repair repository [D] didn't make this immediately obvious 
although given the two commits after a while I managed to work it out
and simply `git checkout ready-multiple-commands` at the command line
fixed things, returning the display to [A].

So the discussion points I'm interested in are:

a. An extra column "Image Branch" with the existing column 
renamed "Disk Branch" would have made my mistake immediately obvious.

b. Such under the covers command line operation may be a corner case(??),
so if not an extra column, a red Status message "Image Branch ready-multiple-commands" or similar would have helped.

c. In the first paragraph of [D] it was not apparent what "working copy" and "repository commit" referred to (although after a while I worked it out from the given commit hashes -- the former was in-Image and the latter on-disk.  But the files on disk are a "working copy" in all other git documentation and it invites confusion not to refer to it like that.  It seems to me we deal with two working copies: an "image working copy" and a "disk working copy". That terminology would have eased discovery of my mistake.

d. Instead of the commit hashes [D], is it feasible to match those to branches/tags and display those.  That would have made my mistake more obvious.

d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

cheers -ben
Reply | Threaded
Open this post in threaded view
|

Re: Iceberg goodness plus ideas

Ben Coman
In reply to this post by Ben Coman
On Sun, 9 Sep 2018 at 23:06, Ben Coman <[hidden email]> wrote:
d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

Sorry, disregard [d.]. I missed that I could click on these to get a description.
cheers -ben
Reply | Threaded
Open this post in threaded view
|

Re: Iceberg goodness plus ideas

Guillermo Polito
In reply to this post by Ben Coman
Hi Ben,

I'm really interested on improving on this. Please read below :)

On Sun, Sep 9, 2018 at 5:07 PM Ben Coman <[hidden email]> wrote:
First, kudos to Iceberg team for detecting the mistake I made messing
around at the command line under the feet of an Iceberg managed repo.
I'm interested in some general discussion of a few ideas before logging any issues.

I had an Iceberg managed repo branch "ready-multiple-commands"
as shown at [A] in the attached pic.
(note that this is "exercism/pharo" not "pharo-project/pharo")
  
I wanted to compare "git log --graph" between a few branches
so I jumped into a command prompt and did so.  Along the way I changed 
branch to "master" from the command line [B].
Then friends arrived and it was six hours until I got back to it
and was presented with "Detached Working Copy" [C],
and I'd forgotten what I'd done.  

Repair repository [D] didn't make this immediately obvious 
although given the two commits after a while I managed to work it out
and simply `git checkout ready-multiple-commands` at the command line
fixed things, returning the display to [A].

So the discussion points I'm interested in are:

a. An extra column "Image Branch" with the existing column 
renamed "Disk Branch" would have made my mistake immediately obvious.

Yes, this could be easily done. We can have a new version with that soon to try it out and see if this improves the situation.
This change would have no significant side effect, and rolling back is cheap.
So I'd like to experiment with this kind of simple UI issues, that may improve the overall understanding.
 

b. Such under the covers command line operation may be a corner case(??),
so if not an extra column, a red Status message "Image Branch ready-multiple-commands" or similar would have helped.

Well, it is not necessarily a corner case, because this will happen for people maintaining external files... At least with current implementation.
We are thinking on adding support for external files, but that will not arrive soon.

Also, the "Detached working copy" is also a bit more complicated than checking out a different branch :).
I'll do some writeup here so people can better understand the motivations behind the current implementation.
I'll try to be clear, but this is much easier to talk about this issues around a blackboard... I can try to do some drawings next time ^^.

So far we decided that Iceberg will not let you work unless you image's working copy is aligned with the repository's working copy/HEAD.
This provokes this kind of situations when touching the repository from outside the image, but we think it is simpler to understand.

An alternative solution could be to let the image and the disk diverge (like implementing in the image some kind of virtual branch). But this could be confusing also. Because this could lead to scenarios where you touch your disk working copy and the image does not "care" them?

Also, take into account that every point of divergence in history will lead to new merge points, and this will increase the possibilities of conflicts.
So, we could have:

Image [commit X]  -  Disk working copy [commit Y] - Remote repository [commit Z]

Imagine that we have a more complex (but flexible?) implementation that allows you to work in this scenario.
Then you choose to pull from the image. 
 - Merging Z with Y could lead to conflicts
 - Merging Y with X too.
 - And merging Z with X too.

So that would lead to a super mess that would be hyper complicated for average users :)
We have thought about this complex scenarios and we decided we wanted to avoid them, because already bare-git is complicated in itself...

Actually, we have been really picky in our merge design and Iceberg only lets you merge 2 commits at a time (even if there are three commits in play when you pull: image, git HEAD and the pulled commit ;)).
 
c. In the first paragraph of [D] it was not apparent what "working copy" and "repository commit" referred to (although after a while I worked it out from the given commit hashes -- the former was in-Image and the latter on-disk.  But the files on disk are a "working copy" in all other git documentation and it invites confusion not to refer to it like that.  It seems to me we deal with two working copies: an "image working copy" and a "disk working copy". That terminology would have eased discovery of my mistake.

There are effectively two working copies, yes :) I'll try to propose a new text for the repair action explanations soon enough. I'll ping you so you can do a double check on it ^^.
 

d. Instead of the commit hashes [D], is it feasible to match those to branches/tags and display those.  That would have made my mistake more obvious.

Not quite. Iceberg's working copy remembers the commit from where the code was loaded, not the branch.
And the branch can move, so it's not necessarily a good source of that information.

What I mean by this is that you will have also a "detached working copy" even if you're in the same branch, but on a different commit.

Imagine you go to the command line, edit some tonel file by hand and commit.
Iceberg will detect the change and tell you you're detached.
 

d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

I think they mean the same, we should review these texts.
Also, consider that one of those repair actions (checkout what is in disk) is just a subset of the other one (checkout an existing branch).
I was thinking if having both is really worth it or not...
 
Keep pushing, I like your feedback, and if you're not satisfied with any of my answers just go on ^^.

cheers -ben


--

   

Guille Polito

Research Engineer

Centre de Recherche en Informatique, Signal et Automatique de Lille

CRIStAL - UMR 9189

French National Center for Scientific Research - http://www.cnrs.fr


Web: http://guillep.github.io

Phone: +33 06 52 70 66 13

Reply | Threaded
Open this post in threaded view
|

Re: Iceberg goodness plus ideas

Ben Coman


On Mon, 10 Sep 2018 at 03:40, Guillermo Polito <[hidden email]> wrote:
Hi Ben,

I'm really interested on improving on this. Please read below :)

On Sun, Sep 9, 2018 at 5:07 PM Ben Coman <[hidden email]> wrote:
First, kudos to Iceberg team for detecting the mistake I made messing
around at the command line under the feet of an Iceberg managed repo.
I'm interested in some general discussion of a few ideas before logging any issues.

I had an Iceberg managed repo branch "ready-multiple-commands"
as shown at [A] in the attached pic.
(note that this is "exercism/pharo" not "pharo-project/pharo")
  
I wanted to compare "git log --graph" between a few branches
so I jumped into a command prompt and did so.  Along the way I changed 
branch to "master" from the command line [B].
Then friends arrived and it was six hours until I got back to it
and was presented with "Detached Working Copy" [C],
and I'd forgotten what I'd done.  

Repair repository [D] didn't make this immediately obvious 
although given the two commits after a while I managed to work it out
and simply `git checkout ready-multiple-commands` at the command line
fixed things, returning the display to [A].

So the discussion points I'm interested in are:

a. An extra column "Image Branch" with the existing column 
renamed "Disk Branch" would have made my mistake immediately obvious.

Yes, this could be easily done. We can have a new version with that soon to try it out and see if this improves the situation.
This change would have no significant side effect, and rolling back is cheap.
So I'd like to experiment with this kind of simple UI issues, that may improve the overall understanding.

Thinking further, this could independently indicate whether the Image Working Copy or the Disk Working Copy are dirty.
 
 

b. Such under the covers command line operation may be a corner case(??),
so if not an extra column, a red Status message "Image Branch ready-multiple-commands" or similar would have helped.

Well, it is not necessarily a corner case, because this will happen for people maintaining external files... At least with current implementation.
We are thinking on adding support for external files, but that will not arrive soon.

From seeing external files in the diff I had guessed this was already done.
In attached pic /dev/src is the Pharo project folder and changes in /docs/ABOUT.md can be seen.
That in itself is very cool.  btw, I love the way remotes show up on this screen.  

One experiment I'd like to try, even though it may clutter the screen a bit more, is on each branch in the left pane
add the commit ID in brackets.  I think this would reinforce that git branches are merely pointers at a commit
which I read is one of the greatest paradigm adjustments for people coming from other versioning systems.
Having different hashes are attached to local/master, remote/origin/master, remote/ben/master 
would reinforce the distinction between them.
btw, Since all the items in the pane are branches/tags, consider renaming "Branches" to "Local Branches" 
or just "Local", or "Local repository" plus "Remotes" to "Remote repositories".

I see here you show two tabs with fixed diffs: 
* Blue selection to HEAD, and;
* Blue selection to previous
Now asking for the moon, what I'd like to try is a second selection in another colour (e.g. purple), 
that perhaps you move holding the ALT key, that would select any two commits to diff.
And also experiment with showing that second selection as either:
* holding down the ALT key to toggle the existing commit list in place to show the purple selection
* since many of us have wide screen, have a second commit list to the right of the existing commit list 
* have a second commit list below the existing commit list
* flexibility of user changing between those three




Also, the "Detached working copy" is also a bit more complicated than checking out a different branch :).
I'll do some writeup here so people can better understand the motivations behind the current implementation.
I'll try to be clear, but this is much easier to talk about this issues around a blackboard... I can try to do some drawings next time ^^.

So far we decided that Iceberg will not let you work unless you image's working copy is aligned with the repository's working copy/HEAD.
This provokes this kind of situations when touching the repository from outside the image, but we think it is simpler to understand.

Definitely a good first approach.  But as we become familiar with git interaction with Images it may open up ideas.
 

An alternative solution could be to let the image and the disk diverge (like implementing in the image some kind of virtual branch). But this could be confusing also. Because this could lead to scenarios where you touch your disk working copy and the image does not "care" them?

I guess the concern is not so much changing disk-working-branch out of synch with the image-working-branch,
but that changing image-working-branch modifies the disk-working-branch and interacting any external changes there is awkward.
Perhaps you can use a stash-like mechanism to place aside the dirty disk-working.
 
Now I wonder if rather than indicating the current branch with the conventional emphasis 
shown in the pic on "master", perhaps above "Branches" add two entries that could independently indicate a separate branch.
e.g...
* "Image Working Copy(master)" 
* "Disk Working Copy(master)"
The latter could have an extra entry at the top of the commit list that showed "working(disk)" in place of a hash if its dirty,
and the former might have two extra entries "working(disk)" and above it "working(image)".
You'd have to suck it to see but this might help promote the paradigm that the Image-Working-Copy
needs to merge into the Disk-Working-Copy before committing into the Local Repository.
which could be selected for a diff comparison. What you would get is an Image-Working-Copy 
to Disk-Working-Copy comparison within a consistent framework of getting diffs between any commit. 


And while the ideas are flowing, in the commit list, where a commit hash aligns with any branch (local or remote)
mark that hash somehow to encourage a user hover over it for a popup to show the aligned branch.
 

Also, take into account that every point of divergence in history will lead to new merge points, and this will increase the possibilities of conflicts.

Maybe not if we manage this divergence "locally" in a stash-like manner. I don't know much about it, 
but the comment "stashes are not a separate branch...they live in their own namespace refs/stash" [1]
makes me think its possible to have a namespace refs/iceberg to track temporary commits sidelining disk-working,
to allow the Image to change branches around dirty disk-branch. Or just use "refs/stash" if its compatible.

IIUC, the stashes are still commits, but just no risk of ending up in repo history.
 
So, we could have:

Image [commit X]  -  Disk working copy [commit Y] - Remote repository [commit Z]

Imagine that we have a more complex (but flexible?) implementation that allows you to work in this scenario.
Then you choose to pull from the image. 
 - Merging Z with Y could lead to conflicts
 - Merging Y with X too.
 - And merging Z with X too.

So that would lead to a super mess that would be hyper complicated for average users :)
We have thought about this complex scenarios and we decided we wanted to avoid them, because already bare-git is complicated in itself...

Actually, we have been really picky in our merge design and Iceberg only lets you merge 2 commits at a time (even if there are three commits in play when you pull: image, git HEAD and the pulled commit ;)).
 
c. In the first paragraph of [D] it was not apparent what "working copy" and "repository commit" referred to (although after a while I worked it out from the given commit hashes -- the former was in-Image and the latter on-disk.  But the files on disk are a "working copy" in all other git documentation and it invites confusion not to refer to it like that.  It seems to me we deal with two working copies: an "image working copy" and a "disk working copy". That terminology would have eased discovery of my mistake.

There are effectively two working copies, yes :) I'll try to propose a new text for the repair action explanations soon enough. I'll ping you so you can do a double check on it ^^.
 

d. Instead of the commit hashes [D], is it feasible to match those to branches/tags and display those.  That would have made my mistake more obvious.

Not quite. Iceberg's working copy remembers the commit from where the code was loaded, not the branch.
And the branch can move, so it's not necessarily a good source of that information.

What I mean by this is that you will have also a "detached working copy" even if you're in the same branch, but on a different commit.

Imagine you go to the command line, edit some tonel file by hand and commit.
Iceberg will detect the change and tell you you're detached.

I just tested this and it didn't seem to work.
Opened Iceberg, for myRepo checked out "master" ==> "Up to date"
Browsed with Windows Explorer to a SomeClass.st  file and made an edit to a method.
Opened new Iceberg, myRepo shows "master" ==> "up to date"

btw, "Detached" is a term for when you have a commit-hash checked out rather than a branch.
I think it risks confusion to reuse that term for a difference between two working copies.
Perhaps "Diverged disk working copy" or similar would be appropriate.
 
 

d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

I think they mean the same, we should review these texts.
Also, consider that one of those repair actions (checkout what is in disk) is just a subset of the other one (checkout an existing branch).
I was thinking if having both is really worth it or not...
 
Keep pushing, I like your feedback, and if you're not satisfied with any of my answers just go on ^^.

Will do, thanks for the encouragement.  
I'm really enjoying using Iceberg now**, bouncing between branches and social interaction on github.
There was obviously some teething pain along the way, but I think the effort has borne good fruit
and is a great part of our path to the future. Onward and upward...

cheers -ben

**Pharo 6.1 standalone with updated iceberg (https://github.com/pharo-vcs/iceberg#update-iceberg)
Reply | Threaded
Open this post in threaded view
|

Re: Iceberg goodness plus ideas

Guillermo Polito


On Mon, Sep 10, 2018 at 5:46 AM Ben Coman <[hidden email]> wrote:


On Mon, 10 Sep 2018 at 03:40, Guillermo Polito <[hidden email]> wrote:
Hi Ben,

I'm really interested on improving on this. Please read below :)

On Sun, Sep 9, 2018 at 5:07 PM Ben Coman <[hidden email]> wrote:
First, kudos to Iceberg team for detecting the mistake I made messing
around at the command line under the feet of an Iceberg managed repo.
I'm interested in some general discussion of a few ideas before logging any issues.

I had an Iceberg managed repo branch "ready-multiple-commands"
as shown at [A] in the attached pic.
(note that this is "exercism/pharo" not "pharo-project/pharo")
  
I wanted to compare "git log --graph" between a few branches
so I jumped into a command prompt and did so.  Along the way I changed 
branch to "master" from the command line [B].
Then friends arrived and it was six hours until I got back to it
and was presented with "Detached Working Copy" [C],
and I'd forgotten what I'd done.  

Repair repository [D] didn't make this immediately obvious 
although given the two commits after a while I managed to work it out
and simply `git checkout ready-multiple-commands` at the command line
fixed things, returning the display to [A].

So the discussion points I'm interested in are:

a. An extra column "Image Branch" with the existing column 
renamed "Disk Branch" would have made my mistake immediately obvious.

Yes, this could be easily done. We can have a new version with that soon to try it out and see if this improves the situation.
This change would have no significant side effect, and rolling back is cheap.
So I'd like to experiment with this kind of simple UI issues, that may improve the overall understanding.

Thinking further, this could independently indicate whether the Image Working Copy or the Disk Working Copy are dirty.

Yes, we could
 
 

b. Such under the covers command line operation may be a corner case(??),
so if not an extra column, a red Status message "Image Branch ready-multiple-commands" or similar would have helped.

Well, it is not necessarily a corner case, because this will happen for people maintaining external files... At least with current implementation.
We are thinking on adding support for external files, but that will not arrive soon.

From seeing external files in the diff I had guessed this was already done.
In attached pic /dev/src is the Pharo project folder and changes in /docs/ABOUT.md can be seen.
That in itself is very cool.  btw, I love the way remotes show up on this screen.  

Well, we HAD to prematurely manage external files for merge, because otherwise a merge could produce lost of changes.
Imagine that you merge only smalltalk code (the previous solution in iceberg < 0.7), then that means that your current branch will not adopt any changes done in external files from the merged commit.

Then, the fact that we show files during checkout is merely "accidental". We had the support for files in the changes tree, so this was just super easy to do :P.

However, we don't have yet support for committing arbitrary files changed in the disk. At commit time, Iceberg only cares about what is checked out *in the image*. So this is the missing support. Implementing this would mean to produce a changes tree that mixes
 - the code in the image
 - the non-code files in the disk

And this could create a new point of conflict (not a git conflict per-se because this is a non-git / iceberg-specific scenario).
So we should decide here what to do when the code files in disk are dirty too.
 

One experiment I'd like to try, even though it may clutter the screen a bit more, is on each branch in the left pane
add the commit ID in brackets.  I think this would reinforce that git branches are merely pointers at a commit
which I read is one of the greatest paradigm adjustments for people coming from other versioning systems.
Having different hashes are attached to local/master, remote/origin/master, remote/ben/master 
would reinforce the distinction between them.
btw, Since all the items in the pane are branches/tags, consider renaming "Branches" to "Local Branches" 
or just "Local", or "Local repository" plus "Remotes" to "Remote repositories".

You mean in the checkout/branch window?
Ah, reading below I see you're talking about the "Repository" window.
 

I see here you show two tabs with fixed diffs: 
* Blue selection to HEAD, and;
* Blue selection to previous
Now asking for the moon, what I'd like to try is a second selection in another colour (e.g. purple), 
that perhaps you move holding the ALT key, that would select any two commits to diff.
And also experiment with showing that second selection as either:
* holding down the ALT key to toggle the existing commit list in place to show the purple selection
* since many of us have wide screen, have a second commit list to the right of the existing commit list 
* have a second commit list below the existing commit list
* flexibility of user changing between those three


Well, the backend support for that is done. It's the UI support missing only.
If you want to play with it, you can:
 1. Right click on a commit -> inspect
 2. In the inspector type:  
      self diffTo: (self repository lookupCommit: 'somecommithash')
And you'll have the tree object.





Also, the "Detached working copy" is also a bit more complicated than checking out a different branch :).
I'll do some writeup here so people can better understand the motivations behind the current implementation.
I'll try to be clear, but this is much easier to talk about this issues around a blackboard... I can try to do some drawings next time ^^.

So far we decided that Iceberg will not let you work unless you image's working copy is aligned with the repository's working copy/HEAD.
This provokes this kind of situations when touching the repository from outside the image, but we think it is simpler to understand.

Definitely a good first approach.  But as we become familiar with git interaction with Images it may open up ideas.
 

An alternative solution could be to let the image and the disk diverge (like implementing in the image some kind of virtual branch). But this could be confusing also. Because this could lead to scenarios where you touch your disk working copy and the image does not "care" them?

I guess the concern is not so much changing disk-working-branch out of synch with the image-working-branch,
but that changing image-working-branch modifies the disk-working-branch and interacting any external changes there is awkward.
Perhaps you can use a stash-like mechanism to place aside the dirty disk-working.

Well, yes, but un-stashing may create conflicts because the dirty changes may touch files you're committing too :).
As a simplification, you can see stashing just as creating a temporary branch and un-stashing as a merge (that does not imply a commit merge)...
 
 
Now I wonder if rather than indicating the current branch with the conventional emphasis 
shown in the pic on "master", perhaps above "Branches" add two entries that could independently indicate a separate branch.
e.g...
* "Image Working Copy(master)" 
* "Disk Working Copy(master)"

Yes, I agree this may be confusing

 
The latter could have an extra entry at the top of the commit list that showed "working(disk)" in place of a hash if its dirty,
and the former might have two extra entries "working(disk)" and above it "working(image)".
You'd have to suck it to see but this might help promote the paradigm that the Image-Working-Copy
needs to merge into the Disk-Working-Copy before committing into the Local Repository.
which could be selected for a diff comparison. What you would get is an Image-Working-Copy 
to Disk-Working-Copy comparison within a consistent framework of getting diffs between any commit. 


And while the ideas are flowing, in the commit list, where a commit hash aligns with any branch (local or remote)
mark that hash somehow to encourage a user hover over it for a popup to show the aligned branch.

We have kind of bubbles in the list already to show tags, we could use them to show branches too, yes

image.png

Still, we may have to work on their "beauty" :)

 
 

Also, take into account that every point of divergence in history will lead to new merge points, and this will increase the possibilities of conflicts.

Maybe not if we manage this divergence "locally" in a stash-like manner. I don't know much about it, 
but the comment "stashes are not a separate branch...they live in their own namespace refs/stash" [1]
makes me think its possible to have a namespace refs/iceberg to track temporary commits sidelining disk-working,
to allow the Image to change branches around dirty disk-branch. Or just use "refs/stash" if its compatible.

IIUC, the stashes are still commits, but just no risk of ending up in repo history.

Check the documentation of pop in


In practice, it does not really matter too much to me if there is a commit or not, and if visible or not. The problem are conflicts, which should be manually resolved by users and add a lot of cognitive load...
 
 
So, we could have:

Image [commit X]  -  Disk working copy [commit Y] - Remote repository [commit Z]

Imagine that we have a more complex (but flexible?) implementation that allows you to work in this scenario.
Then you choose to pull from the image. 
 - Merging Z with Y could lead to conflicts
 - Merging Y with X too.
 - And merging Z with X too.

So that would lead to a super mess that would be hyper complicated for average users :)
We have thought about this complex scenarios and we decided we wanted to avoid them, because already bare-git is complicated in itself...

Actually, we have been really picky in our merge design and Iceberg only lets you merge 2 commits at a time (even if there are three commits in play when you pull: image, git HEAD and the pulled commit ;)).
 
c. In the first paragraph of [D] it was not apparent what "working copy" and "repository commit" referred to (although after a while I worked it out from the given commit hashes -- the former was in-Image and the latter on-disk.  But the files on disk are a "working copy" in all other git documentation and it invites confusion not to refer to it like that.  It seems to me we deal with two working copies: an "image working copy" and a "disk working copy". That terminology would have eased discovery of my mistake.

There are effectively two working copies, yes :) I'll try to propose a new text for the repair action explanations soon enough. I'll ping you so you can do a double check on it ^^.
 

d. Instead of the commit hashes [D], is it feasible to match those to branches/tags and display those.  That would have made my mistake more obvious.

Not quite. Iceberg's working copy remembers the commit from where the code was loaded, not the branch.
And the branch can move, so it's not necessarily a good source of that information.

What I mean by this is that you will have also a "detached working copy" even if you're in the same branch, but on a different commit.

Imagine you go to the command line, edit some tonel file by hand and commit.
Iceberg will detect the change and tell you you're detached.

I just tested this and it didn't seem to work.
Opened Iceberg, for myRepo checked out "master" ==> "Up to date"
Browsed with Windows Explorer to a SomeClass.st  file and made an edit to a method.
Opened new Iceberg, myRepo shows "master" ==> "up to date"

YES, Iceberg will not detect that your disk working copy is dirty.
This is related with what I was saying above on commiting non-code files and merging code files in disk...

BUT, if you commit your changes from the command line, you'll have a detached working copy.
 

btw, "Detached" is a term for when you have a commit-hash checked out rather than a branch.
I think it risks confusion to reuse that term for a difference between two working copies.
Perhaps "Diverged disk working copy" or similar would be appropriate.

Well, Detached Working copy means that the *commit* checked out in the image is effectively different than the commit in the repo's HEAD.
It has nothing to do with branches. Actually changing the branch from behind produces a detached working copy because changing a branch means changing the current commit too :).
 
 
 

d. In [D], its not clear the difference between:
  "Discard local changes"
  "Discard image changes"

I think they mean the same, we should review these texts.
Also, consider that one of those repair actions (checkout what is in disk) is just a subset of the other one (checkout an existing branch).
I was thinking if having both is really worth it or not...
 
Keep pushing, I like your feedback, and if you're not satisfied with any of my answers just go on ^^.

Will do, thanks for the encouragement.  
I'm really enjoying using Iceberg now**, bouncing between branches and social interaction on github.
There was obviously some teething pain along the way, but I think the effort has borne good fruit
and is a great part of our path to the future. Onward and upward...

cheers -ben

**Pharo 6.1 standalone with updated iceberg (https://github.com/pharo-vcs/iceberg#update-iceberg)


--

   

Guille Polito

Research Engineer

Centre de Recherche en Informatique, Signal et Automatique de Lille

CRIStAL - UMR 9189

French National Center for Scientific Research - http://www.cnrs.fr


Web: http://guillep.github.io

Phone: +33 06 52 70 66 13