How to Branch and Merge in Onshape
How to Branch and Merge in Onshape
Introduction 00:00
Versions, Branches and Merges are without a doubt some of the most powerful tools in Onshape. But they can feel confusing, maybe even a little dangerous. Like if you do it wrong, you might overwrite someone's work. Well, that's going to change because I'm going to show you an easy way to understand them. That will make you confident your model is not going to blow up when you merge a branch, even if you're using these tools as part of a team.
I'm Evan, a partner at the product development firm Fractal, let's get to it.
Model History 00:24
To understand Versions in Onshape, you first have to understand Onshapes approach to model history, on shape records, literally every step you take in development from the beginning of time, and it allows you to go back to any step whenever you want. You can think of that like unlimited undo. But it's even more powerful than that, as I'll show you.
If I come up to our version graph here and open that up, you can see what kinds of actions have been recorded in the making of this model. So there's things that you would expect, like sketches, and extrudes. But it also records things like moving the rollback bar, or renaming a part feature or making a new tab at the bottom of the screen here, it really does capture pretty much everything you do in the whole document. And this whole list of changes is document wise [phonetic 01:14]. So if I worked in Ornithopter 1 and made some changes there, and then jumped over to number two and made changes there and all goes into this one single river of history of the entire document.
Now understanding that is critical for your future understanding of how Branches and Merges work, you only get for all of your tabs and assemblies and drawings and any other files you have in your document, you only get one list that captures the development of all of those things together.
Versions 01:39
So each of the rows in this list represents one action that I have taken in my development. And Onshape refers to that as a micro version. If I right click one, I can view the model in the state at that point in time, I can also restore this domain if I didn't like the changes that I've made after that. So you may have guessed by now that a version in Onshape is just a bookmark on one of these micro versions, the step has been recorded either way. And by denoting I have like V3 for example. That just means that that's one that I want to keep track of maybe revisited sometime in the future. So what notable means to me is usually like I have completed a 3d print or had an important client meeting, or sent parts out to have a prototype made. But what's notable for you will depend on you and your workflow.
Now in this case, the reason that I made V 3 is because I realized I needed to change directions with my design. Originally, I thought I would have this lightened lattice structure. But I realized that the wings of the ornithopter need to be able to flex up and down in order to propel it forward. So I made V3, in order to allow me to branch, we'll get to branches in a second. Once I branched, I made all the changes I needed and merged back to main to get back to the design that you see here.
Workspaces 02:55
One other thing I'd like to point out in the version graph is the difference between a version and a workspace.
Versions have a solid dot and they're fixed points in time, they never changed. They're just a bookmark and that's river of history that we've talked about.
A workspace on the other hand, denoted by an open.is, where all the work happens. So these are sort of living workspaces where change is constantly happening, any work you've ever done on the model was done in a workspace.
Okay, so I realized that all I've really done up to this point is defined a bunch of jargon. But we are headed somewhere really cool. And I think when we get there that branching and merging is really going to click for you.
Branches 03:31
So what is a branch?
Well, we've already established that a version is just a bookmark in this list of actions that Onshape is going to be recording either way. And that a workspace is where all the new actions are being added where work happens. When you branch you branch from a version to create a new workspace. And this new workspace has its own list of actions that's independent of any of the other branches. So you can see that B1 now looks exactly like V3, because that's the version that it branches from, but I could do a whole new list of actions here and merge that back into main if I wanted to do it from this point in time. And this list of actions here is going to be completely independent from anything I do in Main and independent from anything I did in another branch like this flexible wings change that we talked about earlier.
For you folks who are still thinking of this kind of like an old cat system you may have come from, you could sort of think of this as a Save As, but it's different in some important ways. One of the most important ways is that once you branch it out, you can get it all back together again, you can have as many concurrent branches as you want, trying different things out, bring in what you like and abandon what you don't like that show you how this actually works. Let's jump over to another example model I have.
Merges 04:46
Okay, we're going to use this little speaker as in example part, if I come up here you can see I have my main workspace and I have V2 so I can right click V2 branch to create a workspace and I'll just keep the default B1. So now we have two workspaces. We have the one in Main and the one in B1, each one has their own list of history, their own list of actions, let's make some changes in both and then see how we can merge them back together.
So in Main, I will rename the tab from speaker to Zen speaker. I'm going to edit this speaker pattern to reduce the number of rings. And I'm going to recolor these parts.
Okay, and if you look in Main here, you can see that these actions have been recorded, we renamed, we edited the pattern, we changed the four parts. So let's go over to our branch and make some changes there. Just to show how a conflict will be resolved, when we merge, I will also change the part color here in the branch to something else. Let's go with purple. I'm also going to edit the speaker pattern. But instead of changing the number of rings, I'm going to change the instance diameter to one millimeter. I am going to edit out the rebuild time here because it's kind of a heavy feature.
And last, I'm going to import some geometry for a speaker from another CAD system. And you can see these tabs have showed up at the bottom here. And if I show the version graph, you can see we change the appearance of the part, we edited the speaker pattern feature. And then when you import it's actually a two step process of importing the file and then translating it. So we have both of those steps here.
Branching is the easy part. It's getting it all back together again, without breaking anything. That's the real trick. How do you know when you won't break something? What if there's a conflict? Which one will win? Does it matter whether it's a sketch feature or an extrude feature? Is there a tie? What happens if there is a tie?
Well, I've seen a number of explanations that left me feeling like I'd have to memorize a whole list of rules and if-thens, in order to be able to predict what will happen when I merge. But I've stumbled upon a way of thinking about it that really helped everything clicked for me. And it's really just one thing to remember. Remember that list of actions from the beginning of the video?
Well, now that you're working in two branches, you have two lists of actions, one for the Main branch and one in B1. When you merge one branch on to the other. You can think of it as taking one of the lists of actions and just stacking it on top of the other list. It's as simple as that. The Active Workspace mean in this case will end up on the bottom and the one being pulled in goes on top. The result is identical to if you had never branch to begin with and just done everything you did in Main, followed by everything you did in B1, identical.
All right, let me show you.
Starting with the steps we did in Main, we renamed the part studio, changed the number of holes and changed it green. The things we did in B1, we changed the part purple, change the whole size and imported the speaker component. The only conflict we had here was that we changed the part color two times, it ended up purple, which is exactly what we would expect when we change the parts in green and then change them to purple. So what about if we merged the other way from Main into B1, the steps from Maine would stack on the steps from B1 like this. And in B one, we changed the part purple, change the whole size and imported the speaker component.
Next came the steps from Main in which we renamed the part studio, changed the number of holes and changed the part to green. Again, color is the only conflict here. But since we changed it purple first and then green, it's going to stay green. All the other steps land us in the same place as before, since none of them overrode each other or caused each other to fail.
Why branch and merge? 08:39
Now you might be thinking that even though you find this interesting, you're not sure if it's very useful. And I would argue that that's because I'm using an overly simplified example just to get the idea across and make it clear. Branching and merging like this becomes more and more valuable, the less straightforward your project is and the more people that are working on it. I've seen a number of creative uses for branching and merging. But in practice for me and for our team, I found that we really only do it for two reasons:
Reason number one is to try something risky. If you are going out and exploring and iterating on your design as is required in order to get to the best solution, you're going to be trying all kinds of stuff. And so branches give you a really low risk way of doing that, that lets you keep what you want and ditch what you don't want.
The other reason that we find ourselves branching and merging is if there are too many cooks in the kitchen. And by that I mean you're getting in each other's way. A couple of ways that you can get in each other's way more working on the same document would include moving the rollback bar, if one user moves the rollback bar, it rolls it back everywhere for everyone, including in assemblies. So if someone's viewing an assembly and someone else rolls back the part studio, the assembly might kind of blew up.
Another reason is part visibility. Imagine you're both working in the same assembly. If you hide a part to see inside of somewhere, it will hide it for everyone. So that's one couple of ways that you might step on each other's toes. And you can just branch out for 30 minutes and then merge it back in, no one will be the wiser.
All right, I know this video is already getting a little bit long. But in order to feel that I've done this subject justice, I feel like I need to leave you with just a couple more tips and cautions.
Be aware where you work 10:12
Warning number one, and this is the most important one, make sure that you're aware of which branch you're working in and keep in mind what actions you actually want there.
When you merge, you don't get to pick and choose which ones go, that entire list is getting merged. So if you made some changes you're in love with and some other ones that you hate, or maybe someone else made some other ones that you hate in the same branch, you're kind of stuck, you can't, you can't have merge, there's no such thing as a partial merge, the best workaround that could save you every once in a while is to right click, part studio tab, copy to clipboard, and then go back to the branch that you want to put it into and paste it in by hitting the check the plus mark and Paste from Clipboard. But even that, it's still just a copy. And you may have to re-associate some part relationships.
Deleting workspaces 10:59
The second thing I want to say is if you are branching, often as you ought to be, then you're going to have a lot of branches. And it's okay to delete them when you're done with them. If it's a small thing, and you're just branching out, you know, too many cooks in the kitchen and you're just branching for 30 minutes. When you've merged it back in, go ahead and delete that branch. Don't do a couple of things, when you have a lot of different workspaces open at once, when Onshape does an automatic update, it pushes them all to the top because the update is considered an action so they are all recently having an action.
Another thing is it prevents what I just described, of working in the wrong place and then not being able to use that work.
And third, it just makes the graph a little bit cleaner and easier to find what you're looking for. But I will caution you if you delete a branch that is one of the few ways you can actually lose work in Onshape. If you delete a branch that has no versions in it, it's gone. If you want to keep the branch around, maybe you want to revisit it later, but you don't really need the Active Workspace there. You can create a version and then delete the branch and it will basically cut all the actions down back to that version. If you need to continue it, you can branch from that version and continue.
Flying it home 12:04
All right, that's going to be it for this one, folks. I hope I've given you an actionable intuition for how to use versions and branches in your daily work. If I have, go ahead and subscribe, hit the bell, so you're notified when I launch more content like this. And if you have any comments, questions, if maybe you use versions and branches in a way I didn't talk about or you disagree with one of my explanations, let me know in the comments. Thanks for watching!
