Merge branch 'doc/api_file_edit' into 'master'

Make file edit error message less specific

See merge request !1007

2 files changed, 10 insertions, 1 deletions

diff --git a/app/services/files/update_service.rb b/app/services/files/update_service.rb
index c631f28749c..a0f40154db0 100644
--- a/app/services/files/update_service.rb
+++ b/app/services/files/update_service.rb
@@ -33,7 +33,7 @@ module Files
       if created_successfully
         success
       else
-        error("Your changes could not be committed, because the file has been changed")
+        error("Your changes could not be committed. Maybe the file was changed by another process or there was nothing to commit?")
       end
     end
   end
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index ae56b04b6ce..b53d60bceec 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -80,6 +80,15 @@ Parameters:
 - `content` (required) - New file content
 - `commit_message` (required) - Commit message
 
+If the commit fails for any reason we return a 400 error with a non-specific
+error message. Possible causes for a failed commit include:
+- the `file_path` contained `/../` (attempted directory traversal);
+- the new file contents were identical to the current file contents, i.e. the
+  user tried to make an empty commit;
+- the branch was updated by a Git push while the file edit was in progress.
+
+Currently gitlab-shell has a boolean return code, preventing GitLab from specifying the error.
+
 ## Delete existing file in repository
 
 ```