Merge pull request #38 from neuroinformatics-unit/cruft-instructions-…

…update

docs/source/programming/Cookiecutter-cruft.md

@@ -2,19 +2,42 @@
 
 Ref: [original docs](https://cruft.github.io/cruft/) and [github repo](https:/cruft/cruft).
 
-First, `pip install cruft`. 
-Then, you have to link your repo to the cookiecutter template by specifying its url.
-You will also need to specify the cookiecutter commit hash, i.e. the version of cookiecutter you used to generate the repo. For now, we have to do this manually by comparing the history.
-Once you have the hash, you can run `cruft link link.to.your.template`. This will create a `.cruft.json` file in your repo.
+## Setup: `cruft link`
+Install: `pip install cruft`. 
 
-Now you can run `cruft diff` to see the changes between your repo and the template. If you are happy with the changes, you can run `cruft update` to update your repo. This will not overwrite all changes you have made, but only the files that have been changed in the template.
+If this is your first time using `cruft`, you have to set it up using the `cruft link` command. You have to specify the URL of your cookiecutter on GitHub.
 
-In the case `cruft update` is not able to apply all the changes, it will create a `.something.rej` file. You can then manually apply the changes to the files. This is a bit tedious, but it's the only way I have found to do it so far.
+```python
+cruft link https://github.com/neuroinformatics-unit/python-cookiecutter
+```
+At this point, cruft will ask you the same questions you were asked when you first generated the repo with cookiecutter. Enter the same answers you did before, but make sure to enter "provide later" when it prompts for "github_repository_url".
 
-I have found that although the link to the repo is correct (`github_repository_url` field), the command `cruft diff` fails, so you might have to change it manually in the `.cruft.json` file to "provide later". 🤷🏻‍♀️
+:::{dropdown} Why 🤷🏻‍♀️?
+I have found that if you enter the correct link to your package's repo in `github_repository_url` field, the command `cruft diff` fails 🤷🏻‍♀️
+:::
 
-`cruft check` will check if your repo is up to date with the template, and basically will just give you a boolean response.
+After you have answered all cookiecutter's questions, `cruft` will prompt you to specify the commit hash, i.e. the older version of cookiecutter you had used to generate the repo. For now, we have to do this manually by searching the history. Example commit hash: `9daec12bffbc32da6a252605c5e67c90028fefc0`. We need to do this because `cruft` will compare your repo with the template, and will only update the files that have changed since the commit hash you specify.
 
+After you have entered the commit hash, `cruft` will create a `.cruft.json` file in your repo containing the URL to the cookicutter, the commit hash, and your responses to cookiecutter's prompts. Please track the changes to this file with git.
+
+## Apply updates: `cruft diff` & `cruft update`
+Now that `.cruft.json` exists, we can run `cruft diff` to see the changes between your repo and the template. At this point, you could manually apply the subset of the changes you want.
+
+You can also ask `cruft` to apply the changes for you by running `cruft update`. You will be prompted to confirm the changes with `y` before they are applied. You can also press `v` to see the changes before confirming.
+
+:::{note}
+`cruft update` will not delete the files you have added to your repo since its creation. It only cares about the files that were generated by cookiecutter.
+
+It also doesn't delete the files that have since been removed from the template. You have to do this manually.
+:::
+
+In case `cruft update` is not able to apply all the changes, it will create a `your_file.rej` file for each conflicting file. Based on these files' contents you can then apply changes manually. Don't forget to remove the `.rej` files when you're done. This is a bit tedious, but it should get easier with more frequent updates.
+
+When `cruft update` is done, you will notice that the `.cruft.json` file has been updated with the new commit hash of the template. Future updates will be based on this commit hash.
+
+`cruft check` will check if your repo is up to date with the template and just give you a boolean response.
+
+## Commit
 Once you are satisfied, commit the changes to a new branch and open a PR to merge it into `main`. 
 
 Now, check if your GitHub actions fail... 🤦🏻‍♀️ If everything is fine, you can merge the PR. 🎉 If not, you will have to fix the errors and repeat the process. 😱