A gentle introduction to the gitea doctor #197

Merged
6543 merged 6 commits from dachary/blog:wip-doctor into master 2 months ago
There is no content yet.
dachary added 1 commit 2 months ago
0e327c85dd
A gentle introduction to the gitea doctor
dachary force-pushed wip-doctor from 0e327c85dd to 324eb1eb1a 2 months ago
dachary force-pushed wip-doctor from 324eb1eb1a to 4f14179a2c 2 months ago
dachary force-pushed wip-doctor from 4f14179a2c to a2659b2ae1 2 months ago
dachary force-pushed wip-doctor from a2659b2ae1 to 10a7cd6d76 2 months ago
dachary force-pushed wip-doctor from 10a7cd6d76 to aabb35bd3a 2 months ago
delvh reviewed 2 months ago
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.
delvh commented 2 months ago

`[gitea doctor](https://docs.gitea.io/en-us/command-line/#doctor) `,
otherwise the link doesn't work.

~~\`~~\[gitea doctor](https://docs.gitea.io/en-us/command-line/#doctor) ~~\`~~, otherwise the link doesn't work.
delvh commented 2 months ago

Perhaps,

[`gitea doctor`](https://docs.gitea.io/en-us/command-line/#doctor)

will work, but I'm not sure about that...

Perhaps, ``` [`gitea doctor`](https://docs.gitea.io/en-us/command-line/#doctor) ``` will work, but I'm not sure about that...
dachary marked this conversation as resolved
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
delvh commented 2 months ago

Given the theme of this article, what about an opening like

### An apple a day keeps the doctor away

Or in our case, Gitea versions below 1.10.5.
Since then, ...
Given the theme of this article, what about an opening like ```md ### An apple a day keeps the doctor away Or in our case, Gitea versions below 1.10.5. Since then, ... ```
dachary marked this conversation as resolved
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.
delvh commented 2 months ago

For instance, in Gitea 1.17 it becomes aware of [orphaned pull requests](https://github.com/go-gitea/gitea/pull/19731) and is able to fix them. If such a problem exists in Gitea 1.16, it does not know about it.

`For instance, in Gitea 1.17 it becomes aware of [orphaned pull requests](https://github.com/go-gitea/gitea/pull/19731) and is able to fix them. If such a problem exists in Gitea 1.16, it does not know about it.`
dachary marked this conversation as resolved
In the following, examples are based on a Gitea 1.16.8 instance you can run as follows:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
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:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
### 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.
delvh commented 2 months ago

could can

... loosing

... Nowadays ,

... data lossage.

~~could~~ can ... lo~~o~~sing ... Nowadays **,** ... data loss~~age~~.
dachary marked this conversation as resolved
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:
delvh commented 2 months ago

The first doctor first version

The **first** `doctor` ~~first~~ version
dachary marked this conversation as resolved
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:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
And then call the `check` that looks interesting:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
Now let's do something bad: remove the permissions from a hook in our repository:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
Run the doctor with the `check` supposed to find that out:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
Ask it to fix this with the `--fix` flag:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
And run it one last time to check all is well:
```
delvh commented 2 months ago
```bash
```` ```bash ````
dachary marked this conversation as resolved
dachary added 1 commit 2 months ago
a85d076b65
apply changes suggested by delvh
dachary added 1 commit 2 months ago
018f7bd225
try to fix quotes + link
Poster

@delvh thanks for your detailed review! I applied all changes. You may want to proofread the wording An apple a day keeps the doctor away first sentence. I'm not sure this is not borken English 😅

@delvh thanks for your detailed review! I applied all changes. You may want to proofread the wording `An apple a day keeps the doctor away` first sentence. I'm not sure this is not borken English 😅
Fogapod reviewed 2 months ago
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.

admin -> admins

admin -> admins

admin -> admins

admin -> admins

admin -> admins

admin -> admins

whoops, looks like i broke it

whoops, looks like i broke it
dachary marked this conversation as resolved

You may want to proofread the wording An apple a day keeps the doctor away first sentence. I'm not sure this is not borken English 😅

Are you talking about the title (An apple a day keeps the doctor away), or the first sentence (or in our case...)?
Why should it be broken English?
To me, it sounds correct:
The title is a saying, and the first "sentence" simply completes the title...
Or am I missing something?

> You may want to proofread the wording `An apple a day keeps the doctor away` first sentence. I'm not sure this is not borken English 😅 Are you talking about the title (An apple a day keeps the doctor away), or the first sentence (or in our case...)? Why should it be broken English? To me, it sounds correct: The title is a saying, and the first "sentence" simply completes the title... Or am I missing something?
Poster

You may want to proofread the wording An apple a day keeps the doctor away first sentence. I'm not sure this is not borken English 😅

Are you talking about the title (An apple a day keeps the doctor away), or the first sentence (or in our case...)?
Why should it be broken English?

The title you wrote is good. I was worried my rewording of the first sentence was borken. Thanks for checking :-)

> > You may want to proofread the wording `An apple a day keeps the doctor away` first sentence. I'm not sure this is not borken English 😅 > > Are you talking about the title (An apple a day keeps the doctor away), or the first sentence (or in our case...)? > Why should it be broken English? The title you wrote is good. I was worried my rewording of the first sentence was borken. Thanks for checking :-)
dachary added 1 commit 2 months ago
2fd71ee9b0
plural admins
delvh approved these changes 2 months ago
### 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.
delvh commented 2 months ago

Now that I think about it: That sentence should most likely be rewritten to
Or in our case, Gitea versions below 1.11.5 except for 1.10.5. Since then, the gitea doctor [is available](https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go))

Now that I think about it: That sentence should most likely be rewritten to `Or in our case, Gitea versions below 1.11.5 except for 1.10.5. Since then, the `gitea doctor` [is available](https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go))`
Poster

Since 1.10.5 & 1.10.6 are exceptions, I reworded the entire paragraph to move that to the end. I find that it helps clarify the first few sentences. What do you think?

Since 1.10.5 & 1.10.6 are exceptions, I reworded the entire paragraph to move that to the end. I find that it helps clarify the first few sentences. What do you think?
delvh marked this conversation as resolved
dachary added 1 commit 2 months ago
19182dab39
clarify 1.10.5 / 1.10.6
dachary added 1 commit 2 months ago
e95b1ed60c
fix missing gitea in examples
lunny approved these changes 2 months ago
6543 approved these changes 2 months ago
6543 merged commit cd316f5acb into master 2 months ago

Reviewers

delvh approved these changes 2 months ago
lunny approved these changes 2 months ago
6543 approved these changes 2 months ago
continuous-integration/drone/pr Build is passing
The pull request has been merged as cd316f5acb.
Sign in to join this conversation.
Loading…
There is no content yet.