| 1 |
Tracking revisions with Git |
| 2 |
=========================== |
| 3 |
|
| 4 |
Bonsai supports tracking the development of your IFC files with a Git |
| 5 |
repository. |
| 6 |
|
| 7 |
Bonsai is an IFC file editor, you can create or load an IFC project, |
| 8 |
change, add or remove BIM objects and save to disk. A Git repository is a |
| 9 |
special folder on your computer where text files, such as IFC files, can be |
| 10 |
efficiently stored and past versions recalled. |
| 11 |
|
| 12 |
Git is also a tool to share files with other people, transmitting only file |
| 13 |
changes, and allowing multiple people to keep local copies of the same |
| 14 |
repository up-to-date. |
| 15 |
|
| 16 |
.. Note:: |
| 17 |
|
| 18 |
If you don't already have Git installed on your system, you will need to |
| 19 |
`Download from the Git website <https://git-scm.com/downloads>`__. |
| 20 |
You may have to restart Blender after installation. |
| 21 |
|
| 22 |
Adding your IFC file to a repository |
| 23 |
------------------------------------ |
| 24 |
|
| 25 |
First, save your file to disk. If the folder is already a repository you can |
| 26 |
*Add* the file in the *IFC Git panel* to tell Git you want to track it, |
| 27 |
otherwise Bonsai will offer to convert the folder into a repository. |
| 28 |
|
| 29 |
.. Warning:: |
| 30 |
|
| 31 |
You probably don't want to turn your entire HOME or User folder into a Git |
| 32 |
repository. Create one folder per project, this folder can contain multiple |
| 33 |
IFC files, optionally in subfolders, plus any resources needed to support |
| 34 |
them. |
| 35 |
|
| 36 |
After adding an IFC file, this action will appear as the most recent item at |
| 37 |
the top of the revision list. |
| 38 |
|
| 39 |
'Committing' changes |
| 40 |
-------------------- |
| 41 |
|
| 42 |
As you work on your IFC project, save the file regularly as usual. When you |
| 43 |
get to a point where it would be useful to later retrieve this state, you need |
| 44 |
to *commit* this to the Git repository. Bonsai gives you three options: |
| 45 |
|
| 46 |
- Showing uncommitted changes will temporarily highlight the differences |
| 47 |
between the saved file and the last committed revision. Green objects are new |
| 48 |
and blue objects exist in the previous revision but have since been modified. |
| 49 |
|
| 50 |
- Discarding uncommitted changes will throw away all your saved changes and |
| 51 |
revert the model to the previous revision. |
| 52 |
|
| 53 |
- Committing changes will save this state of the model in the repository, along |
| 54 |
with a short commit message, the date, and your author details. |
| 55 |
|
| 56 |
.. Tip:: |
| 57 |
|
| 58 |
All revisions need to have some sort of commit message. Typically this |
| 59 |
should be kept to 50 characters or less, but there is no practical limit, |
| 60 |
consider that this message may appear in various places, including on |
| 61 |
drawings, web pages, email subject lines etc.. It is also best to describe the |
| 62 |
status of the revision rather than the changes, ie. "Kitchen now has a |
| 63 |
door" is better than "Add a kitchen door" - but this is a matter of taste. |
| 64 |
|
| 65 |
Visualising differences |
| 66 |
----------------------- |
| 67 |
|
| 68 |
As you add commits, the revision list will build up. Usually you are working at |
| 69 |
the HEAD of a branch, ie. at the top of the list, but you can select items in |
| 70 |
the list to view commit metadata. You can also temporarily colourise the current |
| 71 |
model showing differences between this and any other saved revision - colours |
| 72 |
are the same as above: green objects are new to the current model, blue |
| 73 |
objects have changed in some way, and (if you have an older revision loaded) |
| 74 |
red objects have been deleted. |
| 75 |
|
| 76 |
Viewing object history |
| 77 |
---------------------- |
| 78 |
|
| 79 |
The history of *everything* in the project is tracked in Git, the revision log |
| 80 |
for the currently selected object can be viewed with the Bonsai side-bar. |
| 81 |
|
| 82 |
Retrieving Revisions |
| 83 |
-------------------- |
| 84 |
|
| 85 |
Colourising the model will show you *which* things are different, but it won't |
| 86 |
show you *how* they are different. As long as you have no uncommitted changes, |
| 87 |
you can switch to the selected revision, this will load in Bonsai as a |
| 88 |
full model that can be viewed and even edited. |
| 89 |
|
| 90 |
.. Warning:: |
| 91 |
|
| 92 |
Switching to a different revision actually changes the file on disk before |
| 93 |
loading it in Bonsai. Don't worry, the original hasn't been lost, |
| 94 |
simply select the revision at the top of the list, switch back to |
| 95 |
that and you can continue as before. |
| 96 |
|
| 97 |
Branching |
| 98 |
--------- |
| 99 |
|
| 100 |
Git supports a branched workflow. Say that you want to explore some design |
| 101 |
options, but don't want to mess-up the primary design, you can fork off any |
| 102 |
revision into a new branch and work on this without breaking anything in any |
| 103 |
other branches. |
| 104 |
|
| 105 |
.. Note:: |
| 106 |
|
| 107 |
The primary branch in a Git repository is usually called *main*, though |
| 108 |
this is a convention, and older versions of Git call it *master*. Branch |
| 109 |
names should be short, but can contain unicode characters, emojis etc... |
| 110 |
Branch names can't contain spaces, and have some other minor limitations - |
| 111 |
Bonsai will not allow you to create invalid branch names. |
| 112 |
|
| 113 |
To create a new branch from the current HEAD (ie. the top of the revision list) |
| 114 |
enter a branch name when committing. Leaving this field empty just adds a |
| 115 |
normal commit without creating a branch, however committing a change to an |
| 116 |
earlier revision necessarily implies a new branch, so Bonsai will insist |
| 117 |
that you give it a name. |
| 118 |
|
| 119 |
Each branch can now be navigated separately in the revision list, to switch |
| 120 |
between branches, and to any previous revision in any branch, select the |
| 121 |
revision you are interested-in and switch as before. |
| 122 |
|
| 123 |
.. Tip:: |
| 124 |
|
| 125 |
Conceptually a local branch is equivalent to a remote fork in somebody |
| 126 |
else's copy of your repository, and indeed by adding a remote you |
| 127 |
can fetch their work into a *remote branch* in your local repository. |
| 128 |
|
| 129 |
Merging |
| 130 |
------- |
| 131 |
|
| 132 |
.. Warning:: |
| 133 |
|
| 134 |
Merging is experimental functionality. There are various circumstances |
| 135 |
where a merge will fail, don't worry, this won't break your model but you |
| 136 |
may not want to rely on this functionality without having some experience |
| 137 |
of what changes are likely to merge and what won't. |
| 138 |
|
| 139 |
You can merge changes that exist in a selected revision into the current |
| 140 |
model, even if changes have been made in both revisions - as long as these |
| 141 |
changes don't directly conflict. |
| 142 |
|
| 143 |
.. Note:: |
| 144 |
|
| 145 |
Merging requires the *ifcmerge* tool installed in your `PATH`, if it is |
| 146 |
not installed the merge operator will not be enabled. |
| 147 |
|
| 148 |
When two branches have diverged, merging an IFC model requires *conflict |
| 149 |
resolution* (because added entities may inadvertently reuse the same Step-IDs), |
| 150 |
this means that data on one side or the other may be rewritten by Bonsai in |
| 151 |
order to accommodate both sets of changes. ie. the merge process is |
| 152 |
*asymmetrical*. Bonsai privileges data in the remote `origin/main` branch |
| 153 |
over the local working branch, similarly it privileges data in the local `main` |
| 154 |
branch over any other local working branch. The practical result of this is |
| 155 |
that branches branched-off the `main` branch can generally be merged back into |
| 156 |
`main`, but any sub-branches of these will need to be merged back into their |
| 157 |
parent-branch *before* merging the parent-branch back into `main`. |
| 158 |
|
| 159 |
Tags |
| 160 |
---- |
| 161 |
|
| 162 |
Git tags are useful to label important revisions (think of *TENDER*, |
| 163 |
*CONSTRUCTION*, *RevA* etc..). Tags appear as a prefix in the revision list, |
| 164 |
which can be filtered to only show revisions with tags. Tags for the selected |
| 165 |
revision are also listed in full below the revision list along with their |
| 166 |
optional message text. |
| 167 |
|
| 168 |
.. Note:: |
| 169 |
|
| 170 |
Tag names have the same limitations as branch names, names should be short |
| 171 |
and without spaces, but can contain unicode characters, emojis etc... |
| 172 |
Bonsai will not allow you to create invalid or duplicate tag names. |
| 173 |
Similar to commit messages, tag messages should be 50 characters or less, |
| 174 |
though there is no practical limit. |
| 175 |
|
| 176 |
.. Warning:: |
| 177 |
|
| 178 |
Tags can be deleted locally, but Git is distributed, so if the tag has |
| 179 |
migrated to a remote repository it will reappear when you fetch changes |
| 180 |
from that repository. |
| 181 |
|
| 182 |
Remote operations |
| 183 |
----------------- |
| 184 |
|
| 185 |
Git is a *distributed revision control system*, your local repository can be a |
| 186 |
version of a remote repository and vice-versa. This is conceptually similar to |
| 187 |
local branching except this remote repository could belong to someone else or |
| 188 |
could be hosted by an online Git-forge service. |
| 189 |
|
| 190 |
Your repository can have multiple remote repositories registered, each |
| 191 |
can have potentially multiple branches. |
| 192 |
|
| 193 |
Bonsai allows you to make a local *clone* of a remote repository. You will |
| 194 |
need to provide a URL *origin* to fetch, and an empty local folder to become |
| 195 |
the local repository. |
| 196 |
|
| 197 |
The *Fetch* operator retrieves new data from the remote repository. This isn't |
| 198 |
automatically merged, each branch fetched from the remote repository appears as |
| 199 |
a branch that can be browsed, switched-to or merged just like a local branch. |
| 200 |
These remote branches have prefixed names, eg. `origin/main`. |
| 201 |
|
| 202 |
Once you have committed changes to your local repository, the *Push* operator |
| 203 |
tries to update the remote branch using changes from the selected local branch. |
| 204 |
|
| 205 |
.. Warning:: |
| 206 |
|
| 207 |
Remote repositories can be accessed in multiple ways; ssh, ftp or https |
| 208 |
protocols, for example, can require authentication. This authentication may |
| 209 |
expect you to generate and upload ssh keys, store API tokens, save |
| 210 |
username/password pairs, or use some other form of credential. |
| 211 |
Bonsai can't configure these credentials for you, follow the |
| 212 |
configuration instructions provided by your online service before trying |
| 213 |
actions that require authentication. |
| 214 |
|
| 215 |
Using other Git tools |
| 216 |
--------------------- |
| 217 |
|
| 218 |
Bonsai is not a full Git user interface, but it provides most of the tools |
| 219 |
you will need for day-to-day usage. In general if you need other Git |
| 220 |
functionality you can use external Git tools with your repository and any |
| 221 |
changes will be reflected in the Bonsai UI. |