1 files changed, 89 insertions, 3 deletions
diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md
index e9fbcbc23a9..41cc8bc4aeb 100644
--- a/doc/gitlab-basics/add-file.md
+++ b/doc/gitlab-basics/add-file.md
@@ -1,5 +1,91 @@
-# How to add a file
+---
+type: howto
+---
 
-You can create a file in your [terminal](command-line-commands.md) and push
-to GitLab or you can use the
+# Add a file to a repository
+
+Adding files to a repository is a small, but key task. Bringing files in to a repository,
+such as code, images, or documents, allows them to be tracked by Git, even though they
+may have been created elsewhere.
+
+You can add a file to a repository in your [terminal](#add-a-file-using-the-command-line), and
+then push to GitLab. You can also use the [web interface](../user/project/repository/web_editor.md#upload-a-file),
+which may be a simpler solution.
+
+If you need to create a file first, for example a `README.md` text file, that can
+also be done from the [terminal](command-line-commands.md#create-a-text-file-in-the-current-directory) or
 [web interface](../user/project/repository/web_editor.md#create-a-file).
+
+## Add a file using the command line
+
+Open a [terminal/shell](command-line-commands.md), and change into the folder of your
+GitLab project. This usually means running the following command until you get
+to the desired destination:
+
+```sh
+cd <destination folder>
+```
+
+[Create a branch](create-branch.md) to add your file to, before it is added to the master
+(main) branch of the project. It is not strictly necessary, but working directly in
+the `master` branch is not recommended unless your project is very small, and you are
+the only person working on it. You can [switch to an existing branch](start-using-git.md#work-on-an-existing-branch),
+if you have one already.
+
+Using your standard tool for copying files (for example, Finder in macOS, or File Explorer
+in Windows), put the file into a directory within the GitLab project.
+
+Check if your file is actually present in the directory (if you are in Windows,
+use `dir` instead):
+
+```sh
+ls
+```
+
+You should see the name of the file in the list shown.
+
+Check the status:
+
+```sh
+git status
+```
+
+Your file's name should appear in red, so `git` took notice of it! Now add it
+to the repository:
+
+```sh
+git add <name of file>
+```
+
+Check the status again, your file's name should have turned green:
+
+```sh
+git status
+```
+
+Commit (save) your file to the repository:
+
+```sh
+git commit -m "DESCRIBE COMMIT IN A FEW WORDS"
+```
+
+Now you can push (send) your changes (in the branch `<branch-name>`) to GitLab
+(the git remote named 'origin'):
+
+```sh
+git push origin <branch-name>
+```
+
+Your image will be added to your branch in your repository in GitLab.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->