@teambit/lanes 1.0.486 → 1.0.487

package/artifacts/__bit_junit.xml

@@ -1,21 +1,21 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <testsuites tests="18" failures="0" errors="0" skipped="2">
-  <testsuite name="teambit.lanes/lanes@1.0.486" tests="18" failures="0" errors="0" skipped="2">
+  <testsuite name="teambit.lanes/lanes@1.0.487" tests="18" failures="0" errors="0" skipped="2">
     <testcase classname="dist/lanes.spec.js" name="should list all lanes" time="0.003"/>
-    <testcase classname="dist/lanes.spec.js" name="should return that the lane is up to date when the lane is ahead of main" time="0.01"/>
-    <testcase classname="dist/lanes.spec.js" name="should return that the lane is not up to date when main is ahead" time="0.165"/>
-    <testcase classname="dist/lanes.spec.js" name="should return that the lane is up to date when the lane is ahead of main" time="0.029"/>
-    <testcase classname="dist/lanes.spec.js" name="should return that the lane is not up to date when main is ahead" time="0.162"/>
+    <testcase classname="dist/lanes.spec.js" name="should return that the lane is up to date when the lane is ahead of main" time="0.009"/>
+    <testcase classname="dist/lanes.spec.js" name="should return that the lane is not up to date when main is ahead" time="0.151"/>
+    <testcase classname="dist/lanes.spec.js" name="should return that the lane is up to date when the lane is ahead of main" time="0.022"/>
+    <testcase classname="dist/lanes.spec.js" name="should return that the lane is not up to date when main is ahead" time="0.148"/>
     <testcase classname="dist/lanes.spec.js" name="should restore the deleted lane" time="0.001"/>
     <testcase classname="dist/lanes.spec.js" name="should not throw"/>
     <testcase classname="dist/lanes.spec.js" name="should throw when restoring the lane" time="0.002"/>
-    <testcase classname="dist/lanes.spec.js" name="should create lane history object when creating a new lane" time="0.002"/>
-    <testcase classname="dist/lanes.spec.js" name="should add a record to LaneHistory when snapping" time="0.002"/>
+    <testcase classname="dist/lanes.spec.js" name="should create lane history object when creating a new lane" time="0.001"/>
+    <testcase classname="dist/lanes.spec.js" name="should add a record to LaneHistory when snapping" time="0.001"/>
     <testcase classname="dist/lanes.spec.js" name="should export successfully"/>
-    <testcase classname="dist/lanes.spec.js" name="should not add a record to the lane-history" time="0.001"/>
-    <testcase classname="dist/lanes.spec.js" name="should be able to checkout to a previous state of the lane" time="0.045"/>
-    <testcase classname="dist/lanes.spec.js" name="should be able to revert to a previous history id" time="5.861"/>
-    <testcase classname="dist/lanes.spec.js" name="should not throw when creating the second lane" time="0.152"/>
+    <testcase classname="dist/lanes.spec.js" name="should not add a record to the lane-history"/>
+    <testcase classname="dist/lanes.spec.js" name="should be able to checkout to a previous state of the lane" time="0.036"/>
+    <testcase classname="dist/lanes.spec.js" name="should be able to revert to a previous history id" time="4.794"/>
+    <testcase classname="dist/lanes.spec.js" name="should not throw when creating the second lane" time="0.141"/>
     <testcase classname="dist/lanes.spec.js" name="should save the deleted data into the lane object">
       <skipped/>
     </testcase>

package/artifacts/preview/teambit_lanes_lanes-preview.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports["teambit.lanes/lanes-preview"]=t():e["teambit.lanes/lanes-preview"]=t()}(self,(()=>(()=>{"use strict";var e={898:(e,t,n)=>{var a={id:"teambit.lanes/lanes@1.0.486",homepage:"https://bit.cloud/teambit/lanes/lanes",exported:!0};function o(){const e=i(n(594));return o=function(){return e},e}function i(e){return e&&e.__esModule?e:{default:e}}Object.defineProperty(t,"__esModule",{value:!0}),t.Logo=void 0,o.__bit_component=a,i.__bit_component=a;const r=()=>o().default.createElement("div",{style:{height:"100%",display:"flex",justifyContent:"center"}},o().default.createElement("img",{style:{width:70},src:"https://static.bit.dev/extensions-icons/lanes.svg"}));r.__bit_component=a,t.Logo=r},594:e=>{e.exports=React}},t={};function n(a){var o=t[a];if(void 0!==o)return o.exports;var i=t[a]={exports:{}};return e[a](i,i.exports,n),i.exports}n.d=(e,t)=>{for(var a in t)n.o(t,a)&&!n.o(e,a)&&Object.defineProperty(e,a,{enumerable:!0,get:t[a]})},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),n.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var a={};n.r(a),n.d(a,{compositions:()=>c,compositions_metadata:()=>f,overview:()=>u});var o={};n.r(o),n.d(o,{default:()=>h});var i=n(898);n(594);const r=MdxJsReact,l=TeambitMdxUiMdxScopeContext;var s=["components"];function m(){return m=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var n=arguments[t];for(var a in n)({}).hasOwnProperty.call(n,a)&&(e[a]=n[a])}return e},m.apply(null,arguments)}var d={},p="wrapper";function h(e){var t=e.components,n=function(e,t){if(null==e)return{};var n,a,o=function(e,t){if(null==e)return{};var n={};for(var a in e)if({}.hasOwnProperty.call(e,a)){if(t.includes(a))continue;n[a]=e[a]}return n}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)n=i[a],t.includes(n)||{}.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}(e,s);return(0,r.mdx)(p,m({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(l.MDXScopeProvider,{components:{},mdxType:"MDXScopeProvider"},(0,r.mdx)("p",null,"See more details about these two features here: ",(0,r.mdx)("a",{parentName:"p",href:"https://github.com/teambit/bit/issues/1986"},"Lanes"),". ",(0,r.mdx)("a",{parentName:"p",href:"https://github.com/teambit/bit/issues/1985"},"Snaps"),"."),(0,r.mdx)("p",null,"The following describes the final implementation, which differs from the specification above."),(0,r.mdx)("h2",null,"Synopsis"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"- create a snap: `bit snap` (synopsis similar to the `bit tag`)\n- create a new lane: `bit lane create <name>`\n- list lanes: `bit lane list`\n- switch between lanes: `bit switch <name>`\n- merge lanes: `bit lane merge`\n- show lane details: `bit lane show <name>`\n- diff between lanes: `bit lane diff <values>`\n- track local lane to a remote lane: `bit switch --as`\n- remove a lane: `bit lane remove <name>`.\n- fetch lane objects (without the components): `bit fetch --lanes`\n- import a lane: `bit lane import`\n- export current lane: `bit export`\n- (internal) cat lane object: `bit cat-lane <name>`\n")),(0,r.mdx)("h2",null,"Important points"),(0,r.mdx)("h3",null,"Lane ID"),(0,r.mdx)("p",null,"The Lane id consists of the lane name and the scope. If this is a new lane, the scope is the defaultScope.\nThe ",(0,r.mdx)("inlineCode",{parentName:"p"},"LaneId")," ",(0,r.mdx)("em",{parentName:"p"},"always")," has these two props."),(0,r.mdx)("h3",null,"Performance consideration"),(0,r.mdx)("p",null,"Currently, if it imports with no-deps, it doesn't ask for parents, if it imports with deps it imports with all parents. It is originated from src/api/scope/lib/fetch.ts: ",(0,r.mdx)("inlineCode",{parentName:"p"},"const collectParents = !noDependencies;"),". We need to make a decision here."),(0,r.mdx)("h3",null,"Hash"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Snap's hash is generated by a UUID and then converted into sha1. ",(0,r.mdx)("inlineCode",{parentName:"li"},"sha1(v4())"),"."),(0,r.mdx)("li",{parentName:"ul"},"Lane's hash is generated by a UUID and then converted into sha1. ",(0,r.mdx)("inlineCode",{parentName:"li"},"sha1(v4())"),"."),(0,r.mdx)("li",{parentName:"ul"},"Tag's hash stays the same. Generated by the ",(0,r.mdx)("inlineCode",{parentName:"li"},"Version.id()"),"."),(0,r.mdx)("li",{parentName:"ul"},"Lane's hash doesn't get changed even if the lane has been renamed or its scope changed.")),(0,r.mdx)("h3",null,"Lane Data"),(0,r.mdx)("p",null,"Lane data, for the most cases is a map of component-id:snap-head, in other words, it saves per component the head snap. There are 3 different places where we store such data for different purposes."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"lane-object"),' "Lane" is saved in the scope ',(0,r.mdx)("inlineCode",{parentName:"li"},".bit/objects")," (.bit can be .git/bit locally), it has a unique hash and contains a map of components and their heads. This object exists on both local and remote scopes. Its main purpose is to sync lane-data between scopes. See ",(0,r.mdx)("inlineCode",{parentName:"li"},"Lane")," class (in scope/model) for the implementation details."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"remote-lane")," (component and their heads) is saved in ",(0,r.mdx)("inlineCode",{parentName:"li"},".bit/refs/remote/remote-name/lane-name"),". These refs files are saved in both, local and remote scopes. Its main purpose is to keep track where the remote-heads are per lane. See ",(0,r.mdx)("inlineCode",{parentName:"li"},"RemoteLanes")," class for the implementation details.")),(0,r.mdx)("p",null,"More places that stores lanes related data:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"the currently checked out lane is saved in the scope.json file. (e.g. ",(0,r.mdx)("inlineCode",{parentName:"li"},'{ lanes: { current: "lane-a", tracking: "remote/lane-a" } }'),")."),(0,r.mdx)("li",{parentName:"ul"},"When switching to a remote lane, the .bitmap is updated as well with the remote-name, so then, when cloning the project, it's possible to fetch the remote lane data.")),(0,r.mdx)("p",null,"Summary of when/what lanes data is saved per command:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane create"),": creates a new lane-object and creates a new lane record in scope.json and .bitmap."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit snap"),": adds an entry to the lane-object."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit export"),": pushes the lane-object to the remote. On the remote, the lane-object is created or updated/merged."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit switch --remote"),": 1) creates/updates lane-object in the scope. 2) creates/updates remote-lane. the remote-lane is updated also for main."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit fetch")," or ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import --objects"),": creates/updates remote-lane. the remote-lane is updated also for main. It doesn't update/merge the lane object.")),(0,r.mdx)("h3",null,"Merge during import"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"When the remote is ahead, it's easy, just update the head to the remote-head."),(0,r.mdx)("li",{parentName:"ul"},"When the local and remote have diverged, it's more complex. We need to create a snap-merge that has two parents, one point to the local head and one point to the remote head."),(0,r.mdx)("li",{parentName:"ul"},"On ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import --objects")," (or ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit fetch"),") we don't merge. The remote head is saved in the .bit/refs/remote dir. Then, ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit status")," shows that these components are merge-pending."),(0,r.mdx)("li",{parentName:"ul"},"On ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import <id>")," we do the merge."),(0,r.mdx)("li",{parentName:"ul"},"in case the merge wasn't done and the user is trying to export, the remote blocks is as it finds out that its head doesn't exist on the incoming component."),(0,r.mdx)("li",{parentName:"ul"},"in case the snap-merge failed due to a conflict, it saves the conflict and heads data into ",(0,r.mdx)("inlineCode",{parentName:"li"},".bit/unmerged.json")," file.")),(0,r.mdx)("h3",null,"Merge components"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"to merge an entire lane, use ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane merge"),"."),(0,r.mdx)("li",{parentName:"ul"},"to get updates from a remote lane, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import"),", and then ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit checkout head"),". alternatively, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit merge <component-id>")," in one command."),(0,r.mdx)("li",{parentName:"ul"},"to merge an individual component from a lane to main, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane merge <lane> --pattern <component-id>")," when on main.")),(0,r.mdx)("h3",null,"Useful APIs"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"bit-map ",(0,r.mdx)("inlineCode",{parentName:"li"},"getAllIdsAvailableOnLane()")," filters the currently checked out lane.")),(0,r.mdx)("h3",null,"Remove component from a lane"),(0,r.mdx)("p",null,"Locally, to remove a component from a lane, use ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit remove")," command. It will remove the component from the local lane-object.\nThis change won't affect the remote scope, even after exporting the lane.\nThis is becuase on the remote, the merge-lane process doesn't remove anything, only adds/changes components to the lane object.\nRemember that by default when importing a lane, only the components on the workspace are part of the lane, so the same lane-object, locally can have less components than the remote and obviously in this case we don't want to remove them from the remote on export."),(0,r.mdx)("p",null,"To mark a component as removed on the lane, use ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit remove --delete"),", which will modify the component, mark it as removed, then, on the next snap+export, the remote will be updated.\nOnce a component is marked as removed, it won't be merged during ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit lane merge"),", and won't be imported during ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit lane import"),"."),(0,r.mdx)("h3",null,"Debug issues during merge"),(0,r.mdx)("p",null,"The merge operation performs 3-way merge to minimize the number of conflicts.\nIt searches the common parent of the current-snap and the other-snap. This parent-snap or base-snap is common to these two lanes.\nFor most case, it works as follows:\nIf the base and current has the same data but the other has different data, it means, the other made a change.\nIn which case, no need for conflicts, just bring the data from the other to the local.\nOn the other hand, if the base the other has the same data but the current has different data, then, the current made a change. No need to do anything.\nOnly when the current and the other, both are different, and both are different than the base, there is a conflict."),(0,r.mdx)("p",null,'In case of merging lanes, and it\'s unclear why/how some changes were introduced or marked conflicted, go to the log to find out what is the base-snap and the other-snap.\nThe log message starts with "merging snaps details", and it lists per component-id the base-snap, current-snap and other-snap.\nFrom here, you can investigate the data of each one of the snaps by running ',(0,r.mdx)("inlineCode",{parentName:"p"},"bit cat-object -p <snap>"),".\nTo make this process easier, there are some tools that can help. keep reading."),(0,r.mdx)("h4",null,"source code merges/conflicts"),(0,r.mdx)("p",null,"To find out when a change was introduced to a file or when a file was added/removed, run ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit log-file <file-path>"),".\nIt might be helpful to create a new temporary workspace, import the other lane and run the same there.\nThis way, you get the full picture from both lanes when a change was introduced, and you can see whether it happened before and after the split from the base-snap.\nObviously, ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit log <comp-id> --one-line")," is helpful here to see the distance from each lane from the base-snap."),(0,r.mdx)("h4",null,"dependencies merges/conflicts"),(0,r.mdx)("p",null,"Similar to file-changes, you can run ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit deps blame"),' to understhand when a dependency was introduced/deleted/changed from a component.\nHere again, it\'ll be helpful to import to a new workspace the other lane and run the same there.\nAlso, becuase the dependencies merge is pretty complex, during the merge lots of valuable info is printed to the log.\nHowever, to avoid the extra noise it is not logged as "debug" but as "trace". Before you run the merge, you can add ',(0,r.mdx)("inlineCode",{parentName:"p"},"--log=trace")," to see these messages on the screen.")))}h.isMDXComponent=!0;const c=[i],u=[o],f={compositions:[{displayName:"Logo",identifier:"Logo"}]};return a})()));
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports["teambit.lanes/lanes-preview"]=t():e["teambit.lanes/lanes-preview"]=t()}(self,(()=>(()=>{"use strict";var e={607:(e,t,n)=>{var a={id:"teambit.lanes/lanes@1.0.487",homepage:"https://bit.cloud/teambit/lanes/lanes",exported:!0};function o(){const e=i(n(594));return o=function(){return e},e}function i(e){return e&&e.__esModule?e:{default:e}}Object.defineProperty(t,"__esModule",{value:!0}),t.Logo=void 0,o.__bit_component=a,i.__bit_component=a;const r=()=>o().default.createElement("div",{style:{height:"100%",display:"flex",justifyContent:"center"}},o().default.createElement("img",{style:{width:70},src:"https://static.bit.dev/extensions-icons/lanes.svg"}));r.__bit_component=a,t.Logo=r},594:e=>{e.exports=React}},t={};function n(a){var o=t[a];if(void 0!==o)return o.exports;var i=t[a]={exports:{}};return e[a](i,i.exports,n),i.exports}n.d=(e,t)=>{for(var a in t)n.o(t,a)&&!n.o(e,a)&&Object.defineProperty(e,a,{enumerable:!0,get:t[a]})},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),n.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var a={};n.r(a),n.d(a,{compositions:()=>c,compositions_metadata:()=>f,overview:()=>u});var o={};n.r(o),n.d(o,{default:()=>h});var i=n(607);n(594);const r=MdxJsReact,l=TeambitMdxUiMdxScopeContext;var s=["components"];function m(){return m=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var n=arguments[t];for(var a in n)({}).hasOwnProperty.call(n,a)&&(e[a]=n[a])}return e},m.apply(null,arguments)}var d={},p="wrapper";function h(e){var t=e.components,n=function(e,t){if(null==e)return{};var n,a,o=function(e,t){if(null==e)return{};var n={};for(var a in e)if({}.hasOwnProperty.call(e,a)){if(t.includes(a))continue;n[a]=e[a]}return n}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)n=i[a],t.includes(n)||{}.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}(e,s);return(0,r.mdx)(p,m({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(l.MDXScopeProvider,{components:{},mdxType:"MDXScopeProvider"},(0,r.mdx)("p",null,"See more details about these two features here: ",(0,r.mdx)("a",{parentName:"p",href:"https://github.com/teambit/bit/issues/1986"},"Lanes"),". ",(0,r.mdx)("a",{parentName:"p",href:"https://github.com/teambit/bit/issues/1985"},"Snaps"),"."),(0,r.mdx)("p",null,"The following describes the final implementation, which differs from the specification above."),(0,r.mdx)("h2",null,"Synopsis"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"- create a snap: `bit snap` (synopsis similar to the `bit tag`)\n- create a new lane: `bit lane create <name>`\n- list lanes: `bit lane list`\n- switch between lanes: `bit switch <name>`\n- merge lanes: `bit lane merge`\n- show lane details: `bit lane show <name>`\n- diff between lanes: `bit lane diff <values>`\n- track local lane to a remote lane: `bit switch --as`\n- remove a lane: `bit lane remove <name>`.\n- fetch lane objects (without the components): `bit fetch --lanes`\n- import a lane: `bit lane import`\n- export current lane: `bit export`\n- (internal) cat lane object: `bit cat-lane <name>`\n")),(0,r.mdx)("h2",null,"Important points"),(0,r.mdx)("h3",null,"Lane ID"),(0,r.mdx)("p",null,"The Lane id consists of the lane name and the scope. If this is a new lane, the scope is the defaultScope.\nThe ",(0,r.mdx)("inlineCode",{parentName:"p"},"LaneId")," ",(0,r.mdx)("em",{parentName:"p"},"always")," has these two props."),(0,r.mdx)("h3",null,"Performance consideration"),(0,r.mdx)("p",null,"Currently, if it imports with no-deps, it doesn't ask for parents, if it imports with deps it imports with all parents. It is originated from src/api/scope/lib/fetch.ts: ",(0,r.mdx)("inlineCode",{parentName:"p"},"const collectParents = !noDependencies;"),". We need to make a decision here."),(0,r.mdx)("h3",null,"Hash"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Snap's hash is generated by a UUID and then converted into sha1. ",(0,r.mdx)("inlineCode",{parentName:"li"},"sha1(v4())"),"."),(0,r.mdx)("li",{parentName:"ul"},"Lane's hash is generated by a UUID and then converted into sha1. ",(0,r.mdx)("inlineCode",{parentName:"li"},"sha1(v4())"),"."),(0,r.mdx)("li",{parentName:"ul"},"Tag's hash stays the same. Generated by the ",(0,r.mdx)("inlineCode",{parentName:"li"},"Version.id()"),"."),(0,r.mdx)("li",{parentName:"ul"},"Lane's hash doesn't get changed even if the lane has been renamed or its scope changed.")),(0,r.mdx)("h3",null,"Lane Data"),(0,r.mdx)("p",null,"Lane data, for the most cases is a map of component-id:snap-head, in other words, it saves per component the head snap. There are 3 different places where we store such data for different purposes."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"lane-object"),' "Lane" is saved in the scope ',(0,r.mdx)("inlineCode",{parentName:"li"},".bit/objects")," (.bit can be .git/bit locally), it has a unique hash and contains a map of components and their heads. This object exists on both local and remote scopes. Its main purpose is to sync lane-data between scopes. See ",(0,r.mdx)("inlineCode",{parentName:"li"},"Lane")," class (in scope/model) for the implementation details."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"remote-lane")," (component and their heads) is saved in ",(0,r.mdx)("inlineCode",{parentName:"li"},".bit/refs/remote/remote-name/lane-name"),". These refs files are saved in both, local and remote scopes. Its main purpose is to keep track where the remote-heads are per lane. See ",(0,r.mdx)("inlineCode",{parentName:"li"},"RemoteLanes")," class for the implementation details.")),(0,r.mdx)("p",null,"More places that stores lanes related data:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"the currently checked out lane is saved in the scope.json file. (e.g. ",(0,r.mdx)("inlineCode",{parentName:"li"},'{ lanes: { current: "lane-a", tracking: "remote/lane-a" } }'),")."),(0,r.mdx)("li",{parentName:"ul"},"When switching to a remote lane, the .bitmap is updated as well with the remote-name, so then, when cloning the project, it's possible to fetch the remote lane data.")),(0,r.mdx)("p",null,"Summary of when/what lanes data is saved per command:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane create"),": creates a new lane-object and creates a new lane record in scope.json and .bitmap."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit snap"),": adds an entry to the lane-object."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit export"),": pushes the lane-object to the remote. On the remote, the lane-object is created or updated/merged."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit switch --remote"),": 1) creates/updates lane-object in the scope. 2) creates/updates remote-lane. the remote-lane is updated also for main."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bit fetch")," or ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import --objects"),": creates/updates remote-lane. the remote-lane is updated also for main. It doesn't update/merge the lane object.")),(0,r.mdx)("h3",null,"Merge during import"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"When the remote is ahead, it's easy, just update the head to the remote-head."),(0,r.mdx)("li",{parentName:"ul"},"When the local and remote have diverged, it's more complex. We need to create a snap-merge that has two parents, one point to the local head and one point to the remote head."),(0,r.mdx)("li",{parentName:"ul"},"On ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import --objects")," (or ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit fetch"),") we don't merge. The remote head is saved in the .bit/refs/remote dir. Then, ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit status")," shows that these components are merge-pending."),(0,r.mdx)("li",{parentName:"ul"},"On ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import <id>")," we do the merge."),(0,r.mdx)("li",{parentName:"ul"},"in case the merge wasn't done and the user is trying to export, the remote blocks is as it finds out that its head doesn't exist on the incoming component."),(0,r.mdx)("li",{parentName:"ul"},"in case the snap-merge failed due to a conflict, it saves the conflict and heads data into ",(0,r.mdx)("inlineCode",{parentName:"li"},".bit/unmerged.json")," file.")),(0,r.mdx)("h3",null,"Merge components"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"to merge an entire lane, use ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane merge"),"."),(0,r.mdx)("li",{parentName:"ul"},"to get updates from a remote lane, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit import"),", and then ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit checkout head"),". alternatively, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit merge <component-id>")," in one command."),(0,r.mdx)("li",{parentName:"ul"},"to merge an individual component from a lane to main, run ",(0,r.mdx)("inlineCode",{parentName:"li"},"bit lane merge <lane> --pattern <component-id>")," when on main.")),(0,r.mdx)("h3",null,"Useful APIs"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"bit-map ",(0,r.mdx)("inlineCode",{parentName:"li"},"getAllIdsAvailableOnLane()")," filters the currently checked out lane.")),(0,r.mdx)("h3",null,"Remove component from a lane"),(0,r.mdx)("p",null,"Locally, to remove a component from a lane, use ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit remove")," command. It will remove the component from the local lane-object.\nThis change won't affect the remote scope, even after exporting the lane.\nThis is becuase on the remote, the merge-lane process doesn't remove anything, only adds/changes components to the lane object.\nRemember that by default when importing a lane, only the components on the workspace are part of the lane, so the same lane-object, locally can have less components than the remote and obviously in this case we don't want to remove them from the remote on export."),(0,r.mdx)("p",null,"To mark a component as removed on the lane, use ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit remove --delete"),", which will modify the component, mark it as removed, then, on the next snap+export, the remote will be updated.\nOnce a component is marked as removed, it won't be merged during ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit lane merge"),", and won't be imported during ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit lane import"),"."),(0,r.mdx)("h3",null,"Debug issues during merge"),(0,r.mdx)("p",null,"The merge operation performs 3-way merge to minimize the number of conflicts.\nIt searches the common parent of the current-snap and the other-snap. This parent-snap or base-snap is common to these two lanes.\nFor most case, it works as follows:\nIf the base and current has the same data but the other has different data, it means, the other made a change.\nIn which case, no need for conflicts, just bring the data from the other to the local.\nOn the other hand, if the base the other has the same data but the current has different data, then, the current made a change. No need to do anything.\nOnly when the current and the other, both are different, and both are different than the base, there is a conflict."),(0,r.mdx)("p",null,'In case of merging lanes, and it\'s unclear why/how some changes were introduced or marked conflicted, go to the log to find out what is the base-snap and the other-snap.\nThe log message starts with "merging snaps details", and it lists per component-id the base-snap, current-snap and other-snap.\nFrom here, you can investigate the data of each one of the snaps by running ',(0,r.mdx)("inlineCode",{parentName:"p"},"bit cat-object -p <snap>"),".\nTo make this process easier, there are some tools that can help. keep reading."),(0,r.mdx)("h4",null,"source code merges/conflicts"),(0,r.mdx)("p",null,"To find out when a change was introduced to a file or when a file was added/removed, run ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit log-file <file-path>"),".\nIt might be helpful to create a new temporary workspace, import the other lane and run the same there.\nThis way, you get the full picture from both lanes when a change was introduced, and you can see whether it happened before and after the split from the base-snap.\nObviously, ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit log <comp-id> --one-line")," is helpful here to see the distance from each lane from the base-snap."),(0,r.mdx)("h4",null,"dependencies merges/conflicts"),(0,r.mdx)("p",null,"Similar to file-changes, you can run ",(0,r.mdx)("inlineCode",{parentName:"p"},"bit deps blame"),' to understhand when a dependency was introduced/deleted/changed from a component.\nHere again, it\'ll be helpful to import to a new workspace the other lane and run the same there.\nAlso, becuase the dependencies merge is pretty complex, during the merge lots of valuable info is printed to the log.\nHowever, to avoid the extra noise it is not logged as "debug" but as "trace". Before you run the merge, you can add ',(0,r.mdx)("inlineCode",{parentName:"p"},"--log=trace")," to see these messages on the screen.")))}h.isMDXComponent=!0;const c=[i],u=[o],f={compositions:[{displayName:"Logo",identifier:"Logo"}]};return a})()));

package/artifacts/schema.json

@@ -11749,7 +11749,7 @@
   "componentId": {
     "scope": "teambit.lanes",
     "name": "lanes",
-    "version": "1.0.486"
+    "version": "1.0.487"
   },
   "taggedModuleExports": []
 }

package/dist/{preview-1733541556857.js → preview-1733714450424.js}

@@ -1,5 +1,5 @@
-import * as compositions_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.lanes_lanes@1.0.486/dist/lanes.composition.js';
-import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.lanes_lanes@1.0.486/dist/lanes.docs.mdx';
+import * as compositions_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.lanes_lanes@1.0.487/dist/lanes.composition.js';
+import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.lanes_lanes@1.0.487/dist/lanes.docs.mdx';
 
 export const compositions = [compositions_0];
 export const overview = [overview_0];

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@teambit/lanes",
-  "version": "1.0.486",
+  "version": "1.0.487",
   "homepage": "https://bit.cloud/teambit/lanes/lanes",
   "main": "dist/index.js",
   "componentId": {
     "scope": "teambit.lanes",
     "name": "lanes",
-    "version": "1.0.486"
+    "version": "1.0.487"
   },
   "dependencies": {
     "chalk": "2.4.2",
@@ -31,35 +31,35 @@
     "@teambit/lanes.ui.compare.lane-compare-page": "0.0.162",
     "@teambit/lanes.ui.compare.lane-compare": "0.0.193",
     "@teambit/lanes.ui.navigation.lane-switcher": "0.0.225",
-    "@teambit/checkout": "1.0.486",
-    "@teambit/cli": "0.0.1063",
-    "@teambit/importer": "1.0.486",
+    "@teambit/checkout": "1.0.487",
+    "@teambit/cli": "0.0.1064",
+    "@teambit/importer": "1.0.487",
     "@teambit/legacy.cli.prompts": "0.0.5",
-    "@teambit/scope": "1.0.486",
-    "@teambit/workspace": "1.0.486",
-    "@teambit/express": "0.0.1162",
-    "@teambit/logger": "0.0.1156",
-    "@teambit/graphql": "1.0.486",
-    "@teambit/component-compare": "1.0.486",
-    "@teambit/component-writer": "1.0.486",
-    "@teambit/component": "1.0.486",
-    "@teambit/export": "1.0.486",
+    "@teambit/scope": "1.0.487",
+    "@teambit/workspace": "1.0.487",
+    "@teambit/express": "0.0.1163",
+    "@teambit/logger": "0.0.1157",
+    "@teambit/graphql": "1.0.487",
+    "@teambit/component-compare": "1.0.487",
+    "@teambit/component-writer": "1.0.487",
+    "@teambit/component": "1.0.487",
+    "@teambit/export": "1.0.487",
     "@teambit/harmony.modules.concurrency": "0.0.1",
-    "@teambit/install": "1.0.486",
+    "@teambit/install": "1.0.487",
     "@teambit/lanes.entities.lane-diff": "0.0.168",
     "@teambit/lanes.modules.create-lane": "0.0.34",
     "@teambit/lanes.modules.diff": "0.0.497",
     "@teambit/legacy.component-diff": "0.0.53",
     "@teambit/legacy.component-list": "0.0.54",
-    "@teambit/merging": "1.0.486",
-    "@teambit/remove": "1.0.486",
-    "@teambit/command-bar": "1.0.486",
+    "@teambit/merging": "1.0.487",
+    "@teambit/remove": "1.0.487",
+    "@teambit/command-bar": "1.0.487",
     "@teambit/lanes.hooks.use-lanes": "0.0.275",
     "@teambit/lanes.hooks.use-viewed-lane-from-url": "0.0.228",
     "@teambit/lanes.ui.lane-overview": "0.0.250",
     "@teambit/lanes.ui.menus.use-lanes-menu": "0.0.223",
     "@teambit/ui-foundation.ui.react-router.slot-router": "0.0.512",
-    "@teambit/ui": "1.0.486"
+    "@teambit/ui": "1.0.487"
   },
   "devDependencies": {
     "@types/lodash": "4.14.165",
@@ -70,8 +70,8 @@
     "@teambit/harmony.envs.core-aspect-env": "0.0.63",
     "@teambit/component.testing.mock-components": "0.0.259",
     "@teambit/harmony.testing.load-aspect": "0.0.254",
-    "@teambit/merge-lanes": "1.0.486",
-    "@teambit/snapping": "1.0.486",
+    "@teambit/merge-lanes": "1.0.487",
+    "@teambit/snapping": "1.0.487",
     "@teambit/workspace.testing.mock-workspace": "0.0.27"
   },
   "peerDependencies": {