└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # [ContextKeeper: The State-of-the-Art Session Manager for Visual Studio](https://contextkeeper.io) 2 | 3 | ## **Save and restore** your **complete development context** with a single click πŸ”₯ 4 | 5 | ## **Key Features:** 6 | 7 | - **Save open documents**, **files and the tabs layout** with **breakpoints** and **bookmarks** - restore them later and **make context switching less painful** 8 | - **Automagically restore your last context** when **switching** git **branches** 9 | - **Full multi-monitor and DPIs support** for complex windows and the tabs layout 10 | - Preserve your **exact document layout** and **editor state** 11 | - **Simple JSON file** storage for **easy backup** and **portability** 12 | 13 | **Reclaim your lost productivity**. ContextKeeper safely **preserves your task's progress** so you can seamlessly **switch between different projects or features** without losing your piece of mind 🧠 14 | 15 | Designed with πŸ’– for developers who need to maintain multiple work contexts throughout their day. Do you know [**the real cost of interruption and context switching**](https://contextkeeper.io/blog/the-real-cost-of-an-interruption-and-context-switching/) and **The Law of Context Density** - "*A larger context naturally emerges with a bigger screen real estate.*"? 16 | 17 | 18 | 19 | ## πŸ’‘ **ContextKeeper is currently in the Free Beta with [Optional Founders License](#optional-founders-license), if you will find any issues please [report them](https://github.com/ContextKeeper/ContextKeeper.VisualStudio/issues)**. 20 | 21 | ## πŸ§™β€β™‚οΈ [**Automatically switch contexts** when changing Git branches](#automatic-snapshot-switching-when-changing-branches) and check more detailed [article here](https://contextkeeper.io/blog/automatic-snapshot-switching-when-changing-branches-v1/). 22 | 23 | Are you use using Favorite Documents, Workspace Manager or Task Canvas? [Check how much **value ContextKeeper delivers** when **compared to them**.](#how-much-value-contextkeeper-delivers-when-compared-to-others) 24 | 25 | Looking for **ARM-compatible build** or **VS 2019/2017/2015 support**? [Download from here](https://contextkeeper.io/downloads). 26 | 27 | 28 | ## The supported context is made by: 29 | 30 | * logical state 31 | * your favorites files (non-solution files are also supported) 32 | * last opened files, order and state including last selected line&column 33 | * pinned tabs 34 | * tabs groups 35 | * [breakpoints](#breakpoints-and-bookmarks) 36 | * [bookmarks](#bookmarks) 37 | * [relative paths](#relative-paths) 38 | 39 | * visual state 40 | * main IDE window position and size 41 | * floating windows position and size 42 | * docked state and horizontal/vertical orientation 43 | * tabs groups (including horizontal/vertical orientation) 44 | * [last active and selected tabs](#selected-and-active-documents-in-tab-groups) 45 | * [full screen (maximized) windows support](#full-screen-windows-support) 46 | 47 | **Join the revolution and install it today!** Save at least **3300 minutes/year** = 55 hours = 2.3 days (15 mins x 20 days x 11 months). You need about 15 minutes to fully switch between contexts at the best possible scenario. 48 | 49 | In worst case scenarios **switching to detailed context could take several hours**, one of the [**real** **horror stories**](https://developercommunity.visualstudio.com/t/vs2017-1552-does-not-restore-open-documents/175923#T-N177842-N178047): 50 | 51 | "*Losing this functionality interrupts my workflow beyond imagination. The opened documents represent a "bookmark" for me and I'm barely able to pick up work again without them.* 52 | 53 | *Every time this happens (...) I am willing to put hours into finding a solution, because the thought of losing my opened document state once more after a work session is terrifying. But this time around (...) nothing of the usual remedies helps (...)* **This has added another 20 Minutes and counting to my two hours put into solving this**." 54 | 55 | With ContextKeeper you could **safely store and switch between different programming contexts in seconds πŸ”₯** 56 | 57 | **All opened files, pinned tabs, documents positions, editor state and the tabs layout (horizontal/vertical orientation, docked state and files order)**, **breakpoints and bookmarks** are preserved in a **simple JSON file** 😍 No more dealing with broken .suo file again. 58 | 59 | After installing VSIX package you could access your latest Mental Snapshots by navigating to 60 | 61 | ## View -> Other Windows -> Mental Snapshots 62 | 63 | 64 | 65 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/27hKCBytTdc6vJLjEuzPuX/email) 66 | 67 | By default tool window will open next to **Solution Explorer** 68 | 69 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/pCodzPVj8AFjJrJ5nmoiDA/email) Tool 70 | 71 | You could create a new snapshot using **Create Snapshot** button 72 | 73 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/hLLWTq2itByEq5hZPaQjMi) 74 | 75 | and restore them quickly using few commands from **right-click context menu** 76 | 77 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/bUbWPtYLCdWtkiYcbJKpEP/email) 78 | 79 | 80 | 81 | - **Full Restore** - restores all files including windows state&position, pinned tabs and current line&column for every file, 82 | - **Append Files** - adds all files from a selected snapshot to the current active window, 83 | - **Restore Files** - closes all tabs and restores a snapshot in the same way as Append Files, 84 | - **Update** - update selected snapshot using current visual&logical state 85 | 86 | 87 | 88 | ## Automatic snapshot switching when changing branches 89 | 90 | [![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/5YYSqMkrHsJEEcp5W6sa8y?w=800&fit=max)](https://www.youtube.com/watch?v=BlxAoJpBrZ0) 91 | 92 | When switching to another git branch ContextKeeper will automatically remember current branch snapshot and save it to .contextkeeper/.git-branches folder. Also it will be added to the "Mental Snapshots" UI list at the very top with prefix: 93 | 94 | 95 | 96 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/oyuQheTPi2ohmNMqCevUG9?w=800&fit=max) 97 | 98 | This is the same process that you could do manually before switching branches but now fully automated for your convenience πŸ”₯. The current branch snapshot is always [continuously auto-saved](https://contextkeeper.io/blog/continuous-auto-saving-branch-snapshots-and-git-worktree-support/) when you **add**, **remove** or **change** position of any document tab or window (with tabs). 99 | 100 | Also a git branch could be changed from CLI, Visual Studio or other third-party client and ContextKeeper will detect it auto-magically πŸ§™β€β™‚οΈ and restore snapshot for currently selected branch. 101 | 102 | ## Breakpoints and bookmarks 103 | 104 | Generally, when a snapshot is created, **breakpoints** and **bookmarks** are **saved only for the currently open files**. This behavior differs from that of Visual Studio, which remembers all breakpoints and bookmarks across different sessions for all files. However, I believe that saving them only for open files is more practical. I remember countless examples of finding old breakpoints from days before that were no longer relevant because I was working on a different task. 105 | 106 | The second important thing is that **when they are restored for a file**, all **old breakpoints or/and bookmarks are removed if there were any**, but only for that file and nothing else. 107 | 108 | ### Breakpoints 109 | 110 | Standard and conditional breakpoints are currently supported. When breakpoint is disabled it will be still saved to a snapshot with `IsEnabled` property set to `false` and restored in a disabled state later in the Visual Studio. A single conditional expression is supported with two modes `Is true` and `When changed` 111 | 112 | ![img](https://contextkeeper.io/content/images/2023/03/Breakpoints_JSON.png) 113 | 114 | Although the **supported area is probably enough for about 90-95% of use cases**, there are **some limitations**: 115 | 116 | - only a single conditional expression, 117 | - no support for Hit Count or Filter expressions, 118 | - no support for Actions, β€œRemove breakpoint once” hit or β€œOnly enable when the following breakpoint is hit” options. 119 | 120 | I will be looking for ways to support excluded areas, starting from β€œHit Count” and combined conditions (e. g. Conditional Expression with Hit Count). Unfortunately not every breakpoint’s detail is easily exposed via API but I will be extensively digging in Visual Studio’s internals to cover more use cases. 121 | 122 | ### Bookmarks 123 | 124 | Bookmarks are stored using line numbers in a similar way to breakpoints. 125 | 126 | ![img](https://contextkeeper.io/content/images/2023/03/Bookmarks.png) 127 | 128 | Visual Studio API for bookmarks is really limited; therefore, currently there is no support for: 129 | 130 | - named bookmarks - only the line number is stored but not the bookmark name, 131 | - folders - bookmarks folder structure is not restored. 132 | 133 | I hope you will enjoy using new breakpoints & bookmarks support! 134 | 135 | ## Relative paths 136 | 137 | The feature was one of the missing puzzle pieces, that I always wanted to include. Adding support for **relative path** is essential part to allow **sharing your context** between different **dev environments** and also **inside your team**. It will unlock potential to e. g.: 138 | 139 | - **switching** between **laptop** and **workstation** 140 | - **faster onboarding** developers to new tasks, taking over responsibilities 141 | - **sharing mental models** of the project across **team members** 142 | - **fixing complex bugs easier**, using targeted mental snapshots 143 | 144 | Every time a new snapshot is created it will include `RelativePath` property for every entry in a `*.ck` file. When a snapshot is restored, relative paths will be used by default. There is still `FilePath` property used, as a **fallback strategy**, for global files. All different types of files are supported including: 145 | 146 | - **solution and projects files** 147 | - **"loose" files** (not included in a solution/project) but still part of the folders structure 148 | - **global files** (relative paths cannot be created for them, absolute paths are used) 149 | 150 | ![RelativePath](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/tva8A8pu5XWBxd7JQ5Xvb9) 151 | 152 | ## Selected and active documents in tab groups 153 | 154 | There can be multiple tab groups opened at once and single document **selected** in each: 155 | 156 | ![img](https://contextkeeper.io/content/images/2022/11/Selected-tabs-in-groups.jpg) 157 | 158 | The state of both selected documents is now preserved using `IsSelected` JSON property. 159 | 160 | Additionally, support for the **active** tab was added. When a document has focus while generating the snapshot, it will be tagged internally using `IsActive` property. 161 | 162 | ![img](https://contextkeeper.io/content/images/2022/11/IsActive--property.png) 163 | 164 | ## **Create stash snapshot and restore it later** 165 | 166 | There are two additional commands in the toolbar. **Stash** and **unstash**. The idea is from git workflow but here it's applied to a current context you're working on. You could **quickly save it (stash)** and switch to something else that needs an **urgent attention**. **After stashing** a snapshot **all tabs will be closed automatically**, similarly how stashing works in git - current context is cleared and ready for a new work. 167 | 168 | A stash snapshot is always displayed as a first on the list. Currently only single stash is supported but multiple stashes will be supported in the future. 169 | 170 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/kgAeeubdKzrWxkpK3CECfv/email?w=250) 171 | 172 | A stash has **additional description**, like " **2 hours ago**", to get you additional awareness how long it's awaiting to be unstashed. It's really easy to lose track of time, during coding session, and it will act as an **useful reminder** how long your "main" task was **put on hold**. The **stash timestamp** description **is live updated**. If you decide that more meaningful name for stash snapshot is needed, you can simply rename it and it will become a regular snapshot. 173 | 174 | ### Keyboard shortcuts 175 | 176 | You could **assign your favorites keyboard shortcut** combination for stash and unstash commands from the toolbar. There aren't default shortcuts assigned but I found useful to use: 177 | 178 | - Ctrl+Shift+S, Ctrl+Shift+S for **s**nasphot **s**tashing 179 | - Ctrl+Shift+S, Ctrl+Shift+U for **s**nasphot **u**nstashing 180 | 181 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/aw76uizdFeTKB1Rj1T7L96/email) 182 | 183 | ## Full screen windows support 184 | There is a support added to remember if windows is maximized during snapshot creation. No more problems with restoring maximized windows, especially during git branch switching 😍 Only maximized windows will have additional property serialized in a snapshot. 185 | 186 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/s2WTETYNrgrKaZiP5vW8Bj/email?w=300) 187 | 188 | ## Where the snapshots are stored? 189 | 190 | All snapshots are stored in the **.contextkeeper** folder which is created in the same folder where solution file (.sln) sits. A snapshot is saved using self explanatory JSON format. You could try changing different bits manually and later checking an impact it has during restoring process. 191 | 192 | 193 | 194 | ![img](https://embed.filekitcdn.com/e/ta2FHAgWPvhq7wYzRrVqfZ/aj9BPm1H1e8wRGYwLRqubF/email) 195 | 196 | ## Git worktree support 197 | 198 | The git worktree support, introduced in [v1.3](https://contextkeeper.io/blog/downloads/), allows even [more streamlined context switching](https://stackoverflow.com/a/31951225). If you sometimes clone entire repository when working on a feature I recommend checking [git worktree](https://kickertech.com/git-worktrees-why-would-you-use-it/). Long story short, working tree is like clean, cloned repository but better because: 199 | 200 | - repository "cloning" is done instantly - it's a local operation, 201 | - worktree uses less disk space - there is a single .git folder shared across multiple working trees, 202 | - often more convenient than stashing 203 | 204 | ## How much value ContextKeeper delivers when compared to others 205 | 206 | Below, you'll find a table comparing extensions that work with VS 2022. I've included free extensions, with the exception of Task Canvas, which is a paid one. I've invested several hours testing Favorite Documents, Workspace Manager, and Task Canvas to get a clearer picture of how they all stack up against ContextKeeper. 207 | 208 | | Features supported | ContextKeeper | Task Canvas | Favorite Documents | Workspace Manager | 209 | | ------------------------------------------------------------ | :--------------: | :---------: | :--------------------------: | :---------------: | 210 | | Automatic session switching when changing Git branches | βœ… | ❌ | ❌ | ❌ | 211 | | Restores full Visual Studio's original documents state | βœ… | ❌ | ❌ | ❌ | 212 | | Tabs order | βœ… | ❌ | ❌ | unreliable | 213 | | Tab groups (including horizontal/vertical orientation) | βœ… | ❌ | ❌ | unreliable | 214 | | Document windows positions & size (including floating windows) | βœ… | ❌ | ❌ | unreliable | 215 | | Breakpoints | βœ… | ❌ | ❌ | ❌ | 216 | | Bookmarks | βœ… | ❌ | ❌ | ❌ | 217 | | Last selected tab for every window | βœ… | ❌ | ❌ | unreliable | 218 | | Last active tab among all opened | βœ… | ❌ | ❌ | unreliable | 219 | | Visual Studio independent restore engine | βœ… | partially | ❌ | ❌ | 220 | | Multiple document windows | βœ… | ❌ | ❌ | unreliable | 221 | | Multiple-monitor and DPIs support | βœ… | ❌ | ❌ | unreliable | 222 | | Relative path (portable sessions between environments) | βœ… | limited | limited | ❌ | 223 | | Maximized/Normal state for document windows | βœ… | ❌ | ❌ | ❌ | 224 | | Source control ready sessions files (diffable JSON format) | βœ… | ❌ | ❌ | ❌ | 225 | | Continuous session auto-save for branch snapshots | βœ… | ❌ | ❌ | ❌ | 226 | | One-click append files | βœ… | ❌ | βœ… | ❌ | 227 | | Pinned files | βœ… | ❌ | βœ… | unreliable | 228 | | One-click session update | βœ… | βœ… | ❌(only adding) | unreliable | 229 | | One-click restore | βœ… | βœ… | ❌ | ❌ | 230 | | Shareable session's file between teammates | βœ… | βœ… | ❌(one file for all sessions) | ❌ | 231 | | Last opened files | βœ… | βœ… | βœ… | unreliable | 232 | | Line & column for every file | βœ… | βœ… | βœ… | unreliable | 233 | | Non-solution (external) files | βœ… | βœ… | βœ… | ❌ | 234 | | Not based on the (broken) IVsUIShellDocumentWindowMgr | βœ… | βœ… | βœ… | ❌ | 235 | | Still in an active development (updates in 2023) | βœ… | ❌ | βœ… | ❌ | 236 | | Price | Free during Beta | $49 | Free | Free | 237 | 238 | 239 | 240 | ## Task Canvas 241 | 242 | I must say, I'm a bit surprised by how Task Canvas, the only paid competitor, performed in the comparison. It was built with a different workflow in mind, which is why it lacks in certain areas. However, it's still quite powerful and presents an interesting concept with its independent task canvas (separate, physical tab). Kudos to Sergey for trying something different. I'll take a closer look to see if there are any elements from this concept that could add additional value to ContextKeeper. What are your thoughts on this? 243 | 244 | ## Favorite Documents 245 | 246 | It appears that the most popular extension is based on the simple VS API - `VsShellUtilities.OpenDocument()`. Unfortunately, it lacks more sophisticated use cases. Nonetheless, it's still better than relying solely on Visual Studio's default state engine and the inherently flawed `.suo` file. 247 | 248 | ## Workspace Manager 249 | 250 | The spiritual successor to the (broken) approach of Save All the Tabs, utilizing the `IVsUIShellDocumentWindowMgr.ReopenDocumentWindows()` API. Unfortunately it is nothing more than wrapper for the default Visual Studio state engine, which which has had persistent, unresolved issues for years. It's unreliable, sometimes functioning properly but often failing. My experience with it has been similar to Save All the Tabs, which I tried using with mixed success in the past. 251 | 252 | **The fail of the Save All the Tabs extension**, to **deliver a stable** and **reliable** restore mechanism, **really push me** to work on the a **truly independent session restore engine**. I distinctly recall my thought process during that time - 253 | 254 | > If it doesn't work, I'll at least give it a shot and try to build it. There's nothing wrong with failing, but if I succeed, it will be a big deal one day! I will try to make it the state-of-the-art session manager that Visual Studio has never had but always deserved. 255 | 256 | Later, the context engine has become the heart of ContextKeeper. It was entirely written from scratch, and it is fully independent from Visual Studio session restore API. It is rock solid, and works in VS 2022, including olders versions VS 2019/2017/2015. It has taken thousands of hours and years of work to bring it to a state where it is a true pleasure and an enjoyable experience to use, and to have the session manager that Visual Studio has always deserved. πŸš€ Cause there ain't room for more than one King πŸ‘‘ in this town. 257 | 258 | ## Optional Founders License 259 | 260 | - ***Free Beta***: Currently, all features are available for free during the beta period 261 | - ***Optional License***: [The founder license is available for early adopters](https://contextkeeper.io/license-preorder/) who wish to support development 262 | - ***Future Model***: After the beta (not ETA at this point), basic features will remain free, while more advanced features will require a paid license 263 | 264 | ## Current limitations 265 | 266 | - windows positions are tightly coupled to your (multi) monitor setup, and switching between them is not supported yet (e.g., switching between workstation and laptop with re-adjusted documents size & position to a new resolution). 267 | 268 | 269 | 270 | [The Roadmap](https://contextkeeper.io/blog/roadmap-for-2022/) includes among others: 271 | 272 | - [**breakpoints & bookmarks**](https://contextkeeper.io/blog/launching-breakpoints-bookmarks-support/) (*update:* implemented 15th March 2023) 273 | - [**relative paths**](https://contextkeeper.io/blog/relative-paths-support-in-v1-8-and-contextkeeper-mentioned-on-the-jesse-libertys-podcast/) (*update*: implemented, 1st June 2022) and **machine-independent snapshots restore process** 274 | - **storing snapshots outside of the solution folder** 275 | - [**search dialog**](https://contextkeeper.io/blog/search-dialog-v1-71/) (*update*: implemented, 15th April 2022) 276 | --------------------------------------------------------------------------------