TreeBranch Interface
A collection of functionality associated with a (version-control-style) branch of a SharedTree.
To use, import via fluid-framework/beta.
For more information about our API support guarantees, see here.
This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.
Signature
/** @sealed */
export interface TreeBranch extends IDisposable
Extends: IDisposable
Remarks
A TreeBranch allows for the creation of branches and for those branches to later be merged.
The branch associated directly with the SharedTree is the "main" branch, and all other branches fork (directly or transitively) from that main branch. \
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| dispose(error) | Beta |
void | Dispose of this branch, cleaning up any resources associated with it. |
| fork() | Beta |
TreeBranch | Fork a new branch off of this branch which is based off of this branch's current state. |
| merge(branch, disposeMerged) | Beta |
void | Apply all the new changes on the given branch to this branch. |
| rebaseOnto(branch) | Beta |
void | Advance this branch forward such that all new changes on the target branch become part of this branch. |
Method Details
dispose
Dispose of this branch, cleaning up any resources associated with it.
For more information about our API support guarantees, see here.
Signature
dispose(error?: Error): void;
Remarks
Branches can also be automatically disposed when they are merged into another branch.
Disposing branches is important to avoid consuming memory unnecessarily. In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.
The main branch cannot be disposed - attempting to do so will have no effect.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| error | optional | Error | Optional error indicating the reason for the disposal, if the object was disposed as the result of an error. |
fork
Fork a new branch off of this branch which is based off of this branch's current state.
For more information about our API support guarantees, see here.
Signature
fork(): TreeBranch;
Remarks
Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. merged back into this branch. The branch should be disposed when no longer needed, either explicitly or implicitly when merging into another branch.
Returns
Return type: TreeBranch
merge
Apply all the new changes on the given branch to this branch.
For more information about our API support guarantees, see here.
Signature
merge(branch: TreeBranch, disposeMerged?: boolean): void;
Remarks
All ongoing transactions (if any) in branch will be committed before the merge.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| branch | TreeBranch | a branch which was created by a call to branch(). |
|
| disposeMerged | optional | boolean | whether or not to dispose branch after the merge completes. Defaults to true. The main branch cannot be disposed - attempting to do so will have no effect. |
rebaseOnto
Advance this branch forward such that all new changes on the target branch become part of this branch.
For more information about our API support guarantees, see here.
Signature
rebaseOnto(branch: TreeBranch): void;
Remarks
After rebasing, this branch will be "ahead" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch. This method may only be called on branches produced via branch - attempting to rebase the main branch will throw.
Rebasing long-lived branches is important to avoid consuming memory unnecessarily. In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.
The main branch cannot be rebased onto another branch - attempting to do so will throw an error.
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | The branch to rebase onto. |