@@ -0,0 +6,4 @@
+draft: false
+---
+
+While helping people with their upgrades [in the Gitea forum](https://discourse.gitea.io/t/migration-from-1-2-to-1-16-8/5309) or [at the Hostea clinic](https://forum.hostea.org/t/gitea-upgrade-from-1-14-1-to-1-16-8/90), I realized that few Gitea admin know about the `[gitea doctor](https://docs.gitea.io/en-us/command-line/#doctor)` command and decided to write this blog post as a gentle introduction.

@@ -0,0 +8,4 @@
+
+While helping people with their upgrades [in the Gitea forum](https://discourse.gitea.io/t/migration-from-1-2-to-1-16-8/5309) or [at the Hostea clinic](https://forum.hostea.org/t/gitea-upgrade-from-1-14-1-to-1-16-8/90), I realized that few Gitea admin know about the `[gitea doctor](https://docs.gitea.io/en-us/command-line/#doctor)` command and decided to write this blog post as a gentle introduction.
+
+### Born in 1.10

@@ -0,0 +12,4 @@
+
+The `gitea doctor` command is available for [Gitea 1.10.5](https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go), Gitea 1.10.6 and [Gitea >= 1.11.5](https://github.com/go-gitea/gitea/blob/v1.11.5/cmd/doctor.go). If you are running an older version, it is not available. And since it is designed to run against a specific version of Gitea, it would not be a good idea to try to run the doctor from Gitea 1.16 to verify the sanity of a Gitea 1.2 instance: it will be confused by how the database is organized and a number of other details.
+
+With each version `gitea doctor` improves and gains new capabilities. For instance in Gitea 1.17 it became aware of [orphaned pull requests](https://github.com/go-gitea/gitea/pull/19731) and was able to fix them. If such a problem existed in Gitea 1.16, it would not know about them.

@@ -0,0 +18,4 @@
+
+In the following, examples are based on a Gitea 1.16.8 instance you can run as follows:
+
+```

@@ -0,0 +26,4 @@
+
+And then you can go to the [web interface](https://127.0.0.1:3000/) to create a `test` repository, with an initial `README.md` file. When this is done the doctor can be called as follows:
+
+```

@@ -0,0 +71,4 @@
+
+### What does the doctor know?
+
+Although the `doctor` could be compared to [fsck(8)](https://en.wikipedia.org/wiki/Fsck), it does not know everything. It took decades for `fsck` to become the ultimate authority on finding problems on file systems and reliably fixing them without loosing data. Nowadays only a handful of people in the world are brave enough to manually attempt a file system recovery when `fsck` cannot recover from a data lossage.

@@ -0,0 +73,4 @@
+
+Although the `doctor` could be compared to [fsck(8)](https://en.wikipedia.org/wiki/Fsck), it does not know everything. It took decades for `fsck` to become the ultimate authority on finding problems on file systems and reliably fixing them without loosing data. Nowadays only a handful of people in the world are brave enough to manually attempt a file system recovery when `fsck` cannot recover from a data lossage.
+
+The `doctor` first version is two years old and Gitea admins are still routinely running SQL queries against the database or moving files around when trying to figure out why a Gitea instance is not behaving as it should. It is however worth checking if the doctor does not already have a solution by listing all it can do:

@@ -0,0 +75,4 @@
+
+The `doctor` first version is two years old and Gitea admins are still routinely running SQL queries against the database or moving files around when trying to figure out why a Gitea instance is not behaving as it should. It is however worth checking if the doctor does not already have a solution by listing all it can do:
+
+```

@@ -0,0 +96,4 @@
+
+And then call the `check` that looks interesting:
+
+```

@@ -0,0 +112,4 @@
+
+Now let's do something bad: remove the permissions from a hook in our repository:
+
+```

@@ -0,0 +118,4 @@
+
+Run the doctor with the `check` supposed to find that out:
+
+```

@@ -0,0 +126,4 @@
+
+Ask it to fix this with the `--fix` flag:
+
+```

@@ -0,0 +135,4 @@
+
+And run it one last time to check all is well:
+
+```

@@ -0,0 +6,4 @@
+draft: false
+---
+
+While helping people with their upgrades [in the Gitea forum](https://discourse.gitea.io/t/migration-from-1-2-to-1-16-8/5309) or [at the Hostea clinic](https://forum.hostea.org/t/gitea-upgrade-from-1-14-1-to-1-16-8/90), I realized that few Gitea admin know about the `[gitea doctor](https://docs.gitea.io/en-us/command-line/#doctor)` command and decided to write this blog post as a gentle introduction.

@@ -0,0 +10,4 @@
+
+### An apple a day keeps the doctor away
+
+Or in our case, Gitea versions below 1.10.5. Since then, the `gitea doctor` [is available](https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go) (as well as Gitea 1.10.6 and then for [Gitea >= 1.11.5](https://github.com/go-gitea/gitea/blob/v1.11.5/cmd/doctor.go)). If you are running an older version, it is not available. And since it is designed to run against a specific version of Gitea, it would not be a good idea to try to run the doctor from Gitea 1.16 to verify the sanity of a Gitea 1.2 instance: it will be confused by how the database is organized and a number of other details.