First pass to bring /gitlab-basics to SSoT standardsdocs-ssot-gitlab-basics-1

Removes duplicated information, and combines sections and files
together when they are duplicated or highly related. Also adds
intros to all pages and sections missing intros, and troubleshooting
sections to pages that may need them in the future. Links more to
other docs, and clarifies language when abosolutely necessary, and
adds angle brackets to sample parameters.

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. -->