Debian Codegraph @

src/bonsai/docs/guides/authoring/git_support.rst

raw
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.