SolarStrike Software

OK, there's a ton of information I'd like to go over here, but I'll try to keep it short and to the point and only cover one topic at a time.
First let me explain what this beautiful little piece of art is supposed to be. It's a diagram showing a project that was branched twice, and how the different merges take place.
The project starts at point X. The black bar represents the 'master' branch, while blue and red represent different branches (and will be referred to be color for clarity sake).
Each circle on the diagram represents a commit into that branch.
When a merge takes place, the color of the line (as well as the related commit) will be that of the origin, or 'from', branch.
Note that a merge will look like an extra commit on the receiving branch, hence the reason they are circles.

So to understand how and when commits hit the different branches, we're going to step through this together. Our first commit into the project is point A. The blue branch is created at this point (but does not have any new commits added to it for quite some time). That is, both master and blue branches contain everything up to the A commit.

The master branch has commit B added to it, and then the red branch is split from this commit. As of this time, both master and red branches contain X, A, B, while the blue branch only contains X and A.

Commits C and D are created into master and blue respectively at roughly the same time, however, no merges have yet taken place. As of now, master contains X, A, B, and C while blue still only contains X, A, and D.

Finally, our first merge takes place, merging commit D from blue into master at the point that I for some reason forgot to name. blue branch remains unchanged but master now contains D in addition to all previous commits.

Master now has a new commit (E) added and then merges into red at point F. Because when we merge we are including all commits up until that point, both master and red branch now contain X, A, B, C, D, and E commits, while blue is still only X, A, and D.

Commit G is added to red and then merged into blue branch at point H (notice we skipped over the black line). Red and blue branches are now contain all commits (the commits from red are moved into blue, but since red also contains the commits from master, we move those over as well). Since nothing was merged into master yet, it still only has up to E.


Does this help explain how commits and merging into multiple branches work?

Now I'll answer those previous questions you had.

What I want to know is can I use the experimental branch like I use my working copy, just add changes to it as I go along?

Sure! That's totally fine and is actually how things should be done.

Here's a scenario; say I do a change A in response to a user query but I don't commit it to the master because it's minor. Then a while later I add change B in response to another query which I also don't commit. Then sometime later I'm working on change K and it's proving to be tricky but people are requesting that I commit changes from J. Assuming I've been saving the changes to the experimental channel, can I go back to J and commit (or push) that to the master then return to K and continue working on it?

Yes and no. If you were to push J, it would (by default) contain everything else (refer to the above diagram for an explanation). You should be able to select which commits you actually want to move over somehow, but I'm not really equipped to teach you how to do that with TortoiseSVN. When you go through the process of a pull request (what you do to create a merge), you'll be asked to review the changes before actually merging the trees. This is the point where you'd deselect everything but what you want.

And that's why things get messy and hard to keep track of. In this case, the recommended course of action would be one of two things:
1) Switch to the master branch. Your files will automatically be converted over to the snapshot of what master contains so you don't have to worry about changes from experimental getting in the way. Make the required changes and commit so that master now contains the fix you need to roll out immediately. You can then merge this into experimental, then switch back to experimental and continue working.

2)Create another branch, name it 'hotfix' or something. Make your commits into that and then merge into master (and optionally experimental). Once merged, you can delete the hotfix branch if you no longer will use it (but can re-create it again later).

What I'm trying to say is if you branch the experimental version at point A of the master, isn't the experimental branch essentially what is at A plus any changes made in the experimental branch?

Yup. Plus anything that gets merged into it if you should decide to pull in anything.

If you push the changes in the experimental branch to the master at point B then at that point aren't the experimental and master branches the same?

Should be, but master could contain additional commits. Ignoring that, yes.

From then on can't the experimental branch now be considered a change from point B in the master?

For the most part, yes. Now it's possible for data to be inserted into older points, but that's getting into much more advanced stuff that we don't need to worry about at all.

Lets go through an example here.

First, we create a new project and add some very basic stuff into main.lua: Remember to Sync/Publish (button in top right) after your commits to ensure the remote (server side; aka Github) is informed of it


We then created a new branch (button in top-left-ish), 'events', and added some code to handle events: Notice we add another file, events.lua, and we also change function macro.event() in main.lua. Sync/Publish again!

At this point, if we switch branches back to master, our folder will only contain main.lua and will not have the changes we just made; events.lua will look like it's been deleted (and in essence, it has been, but don't worry! If we switch back to events branch, our changes come back too). I only point this out because it is important to note that your local files will literally be an exactly copy of what your selected branch should be; when you switch branches, new files can be added, files can be deleted, and files can be changes to match what your branch should have.


Lets say we're ready to merge the change from the events branch into master. While you can do merges from within Github client, it's pretty terrible so I highly recommend just using website. To do this, go to the project repository page: Notice that since we have master selected, events.lua does not show in our file list below. Click the green (highlighted in the screenshot) button to create a pull request so we can merge.

On the left button, select where you're merging to (master in our case) on the left, and where you're merging from on the right.
We will now see our potential changes so we can confirm everything before we create the pull request (PR). Looks fine, so we can can click the big green button to continue, add a comment, and finally create the PR.
The PR is in place so we can go ahead and click the green button. It should turn purple indicating we're all merged up.


We should now move back to Github client and select the master branch (if we haven't already). Click the Sync button (top right) to make sure our local copy gets the merge (as well as potentially any commits from other people). We can now see our merge as a commit and have all of our changes from the events branch in master:

Nice tutorial. Thanks.

One thing I want to clarify. In the top diagram, when you merge D into the master it takes the changes added at D and applies them to the master, right? So the fact that the blue branch does have B and C doesn't cause it too loose any changes from B and C. I guess this is a situation where you could get a conflict if D changes the same parts as B or C.

I'll see what I can do with TortoiseSVN but if I have trouble, you use Github Desktop, right? I'll give that a try if I have trouble. And you said you prefer to use the web site to do merges?

Sorry I ignored your reply. I didn't actually see the additional questions you posted.

rock5 wrote:So the fact that the blue branch does have B and C doesn't cause it too loose any changes from B and C. I guess this is a situation where you could get a conflict if D changes the same parts as B or C.

Your wording was off but I think you're saying blue does not have B and C (only D), but when merged into master, D could conflict with B or C. Yes; if D makes changes with B or C, in the same file(s), that could be seen as ambiguous and unable to be automatically merged. In this case, a temp branch is automatically created and used to resolve the conflict and then that would be merged.

you use Github Desktop, right?

Yes, I do. I have Tortoise around, but I'm not sure how well it actually plays with Git features.

And you said you prefer to use the web site to do merges?

Yeah. It is a lot easier to actually understand the changes taking place, and to manage them, on the webpage rather than in the client. Github's client has been taken over by UI designers (that previously only really worked on Apple products) and as a result it has become a pretty, but at times intuitive or broken mess.