From 13d5cdf8f390a0fb8f84f7d27859c709a573fc88 Mon Sep 17 00:00:00 2001
From: bkroll <10960255+bkroll@users.noreply.github.com>
Date: Mon, 23 Jul 2018 14:39:17 +0200
Subject: [PATCH] documentation as requested in go-gitea/gitea#3817

---
 .../doc/installation/from-binary.en-us.md     | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md
index f393333e4..8847b3083 100644
--- a/docs/content/doc/installation/from-binary.en-us.md
+++ b/docs/content/doc/installation/from-binary.en-us.md
@@ -90,6 +90,18 @@ cp gitea /usr/local/bin/gitea
 
 See how to create [Linux service]({{< relref "run-as-service-in-ubuntu.en-us.md" >}})
 
+## Updating to a new version
+
+You can update to a new version of gitea by replacing the binary at `/usr/local/bin/gitea`. 
+The binary file name should not be changed during the update to avoid problems 
+in existing repositories. 
+
+If you have carried out the installation steps as described above, the binary should 
+have the generic name `gitea`. Do not change this, i.e. to include the version number. 
+
+See below for troubleshooting instructions to repair broken repositories after 
+an update of your gitea version.
+
 ## Troubleshooting
 
 ### Old glibc versions
@@ -107,3 +119,20 @@ For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:30
 bind: address already in use` gitea needs to be started on another free port. This
 is possible using `./gitea web -p $PORT`. It's possible another instance of gitea
 is already running.
+
+### Git error after updating to a new version of gitea
+
+If the binary file name has been changed during the update to a new version of gitea, 
+git hooks in existing repositories will not work any more. In that case, a git 
+error will be displayed when pushing to the repository.
+
+```
+remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
+```
+
+The `[...]` part of the error message will contain the path to your previous gitea 
+binary.
+
+To solve this, go to the admin options and run the task `Resynchronize pre-receive, 
+update and post-receive hooks of all repositories` to update all hooks to contain
+the new binary path.
\ No newline at end of file