misc: Update lab-setup guide

Add instructions on how to store progress before pulling changes.
Recommend that each laboratory should have its own branch to avoid
rebase conflicts.

Signed-off-by: Alex Apostolescu <[email protected]>

misc/lab-setup.md

@@ -1,38 +1,78 @@
 # Setting up the Lab Environment
 
-If you have already cloned the repository, make sure it is updated:
+## Prerequisites
+
+You can work on any Linux setup (native install, `WSL`, `VM`), but we strongly recommend you use the [`operating-systems` class VMs](https://cs-pub-ro.github.io/operating-systems/resources#virtual-machine).
+
+## Cloning the repository
+
+If you haven't already cloned the repository, do so and you are ready to go:
 
 ```console
+student@os:~$ git clone https://github.com/cs-pub-ro/operating-systems.git
 student@os:~$ cd operating-systems
-
-student@os:~/operating-systems$ git pull --rebase
 ```
 
-The command may fail if you have uncommitted changes.
-If that is the case, stash your changes, retry, and pop the stash:
+## Getting the latest changes
+
+Each time you start a new laboratory, you should ensure you have the latest changes.
+If you have no local changes, you can simply run `git pull` and you are ready to go:
 
 ```console
-student@os:~/operating-systems$ git stash
+student@os:~$ cd operating-systems
+student@os:~/operating-systems$ git status # Check if you have unstaged changes
+On branch <not-important>
+nothing to commit, working tree clean
 
+# "working tree clean" means that you have no changes
 student@os:~/operating-systems$ git pull --rebase
-
-student@os:~/operating-systems$ git stash pop
 ```
 
-If you haven't already cloned the repository, do so and then enter the repository:
+If the `git status` output differs, follow the [instructions to save your progress](#save-progress-and-prepare-next-lab).
 
-```console
-student@os:~$ git clone https://github.com/cs-pub-ro/operating-systems
+## Save Progress and Prepare next lab
 
-student@os:~$ cd operating-systems
-```
+1. Check if you have unstaged changes that might be lost:
 
-Navigate to a chapter's lab directory:
+ ```console
+ student@os:~$ cd operating-systems
+ student@os:~/operating-systems$ git status
+ On branch <not-important>
+ Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: main.c
+ ```
 
-```console
-student@os:~/operating-systems$ cd content/chapters/<chapter-name>/lab/
-```
+ If `git status` states "work tree clean", you should follow the [instructions to pull latest changes](#getting-the-latest-changes) instead.
 
-The possible options are: `software-stack`, `data`, `compute`, `io` and `app-interact`.
+1. Create a commit to store your changes:
 
-You can work on any Linux setup (native install, `WSL`, `VM`), but we strongly recommend you use the [`operating-systems` class VMs](https://cs-pub-ro.github.io/operating-systems/resources#virtual-machine).
+ ```console
+ student@os:~/operating-systems$ git add -f . # Use -f as `support/` directories are ignored
+ student@os:~/operating-systems$ git commit -m "Store progress for lab X"
+ student@os:~/operating-systems$ git status # double check that everything was commited
+ On branch <not-important>
+ nothing to commit, working tree clean
+ ```
+
+1. Create a new branch for lab Y:
+
+ ```console
+ student@os:~/operating-systems$ git checkout -b lab-Y main # Replace Y with lab number
+ student@os:~/operating-systems$ git pull origin main # Get latest changes from origin/main
+ ```
+
+1. (Optional) Finding previous labs
+
+ Assuming you followed the instructions in this section, you can find your previous work on other branches:
+
+ ```console
+ student@os:~/operating-systems$ git branch
+ main
+ lab-1
+ lab-2
+ * lab-3
+ student@os:~/operating-systems$ git checkout lab-2
+ Switched to branch 'lab-2'
+ ```