Merge branch 'docs-aqualls-create-warnings1' into 'master'

Word and line edits for Create documentation

See merge request gitlab-org/gitlab!52731

doc/topics/git/git_rebase.md

@@ -69,7 +69,7 @@ changes by resetting `my-feature-branch` against `my-feature-branch-backup`:
    ```
 
 Note that if you added changes to `my-feature-branch` after creating the backup branch,
-you will lose them when resetting.
+you lose them when resetting.
 
 ### Regular rebase
 
@@ -116,7 +116,7 @@ example, `release-10-3`. You can also replace `origin` with other remote
 repositories, for example, `upstream`. To check what remotes you have linked to your local
 repository, you can run `git remote -v`.
 
-If there are [merge conflicts](#merge-conflicts), Git will prompt you to fix
+If there are [merge conflicts](#merge-conflicts), Git prompts you to fix
 them before continuing the rebase.
 
 To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
@@ -126,13 +126,13 @@ and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
 
 You can use interactive rebase to modify commits. For example, amend a commit
 message, squash (join multiple commits into one), edit, or delete
-commits. It is handy for changing past commit messages,
-as well as for organizing the commit history of your branch to keep it clean.
+commits. Use a rebase for changing past commit messages,
+and organizing the commit history of your branch to keep it clean.
 
 NOTE:
 If you want to keep the default branch commit history clean, you don't need to
-manually squash all your commits before merging every merge request;
-with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md)
+manually squash all your commits before merging every merge request.
+With [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md),
 GitLab does it automatically.
 
 When you want to change anything in recent commits, use interactive
@@ -155,7 +155,8 @@ For example, if you're using [Vim](https://www.vim.org/) as the text editor in
 a macOS's `ZSH` shell, and you want to **squash** all the three commits
 (join them into one):
 
-1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode.
+1. Press <!-- vale gitlab.FirstPerson = NO --> <kbd>i</kbd> <!-- vale gitlab.FirstPerson = YES -->
+   on your keyboard to switch to Vim's editing mode.
 1. Navigate with your keyboard arrows to edit the **second** commit keyword
    from `pick` to `squash` (or `s`). Do the same to the **third** commit.
    The first commit should be left **unchanged** (`pick`) as we want to squash
@@ -163,8 +164,8 @@ a macOS's `ZSH` shell, and you want to **squash** all the three commits
 1. Press <kbd>Escape</kbd> to leave the editing mode.
 1. Type `:wq` to "write" (save) and "quit".
 1. Git outputs the commit message so you have a chance to edit it:
-   - All lines starting with `#` will be ignored and not included in the commit
-   message. Everything else will be included.
+   - All lines starting with `#` are ignored and not included in the commit
+   message. Everything else is included.
    - To leave it as it is, type `:wq`. To edit the commit message: switch to the
    editing mode, edit the commit message, and save it as you just did.
 1. If you haven't pushed your commits to the remote branch before rebasing,
@@ -180,8 +181,8 @@ for a deeper look into interactive rebase.
 ## Force-push
 
 When you perform more complex operations, for example, squash commits, reset or
-rebase your branch, you'll have to _force_ an update to the remote branch,
-since these operations imply rewriting the commit history of the branch.
+rebase your branch, you must _force_ an update to the remote branch.
+These operations imply rewriting the commit history of the branch.
 To force an update, pass the flag `--force` or `-f` to the `push` command. For
 example:
 
@@ -267,6 +268,6 @@ To fix conflicts locally, you can use the following method:
    Up to this point, you can run `git rebase --abort` to stop the process.
    Git aborts the rebase and rolls back the branch to the state you had before
    running `git rebase`.
-   Once you run `git rebase --continue` the rebase **cannot** be aborted.
+   After you run `git rebase --continue` the rebase **cannot** be aborted.
 
 1. [Force-push](#force-push) to your remote branch.

doc/topics/git/lfs/index.md

@@ -14,13 +14,13 @@ larger than 1GB to preserve performance.
 
 ![Git LFS tracking status](img/lfs-icon.png)
 
-An LFS icon is shown on files tracked by Git LFS to denote if a file is stored
-as a blob or as an LFS pointer.
+Files tracked by Git LFS display an icon to indicate if the file is stored as a
+blob or an LFS pointer.
 
 ## How it works
 
 Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication
-to authorize client requests. Once the request is authorized, Git LFS client receives
+to authorize client requests. After the request is authorized, Git LFS client receives
 instructions from where to fetch or where to push the large file.
 
 ## GitLab server configuration
@@ -35,18 +35,18 @@ Documentation for GitLab instance administrators is under [LFS administration do
 
 ## Known limitations
 
-- Git LFS v1 original API is not supported since it was deprecated early in LFS
-  development
-- When SSH is set as a remote, Git LFS objects still go through HTTPS
-- Any Git LFS request will ask for HTTPS credentials to be provided so a good Git
-  credentials store is recommended
-- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have
-  to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting))
+- Git LFS v1 original API is not supported, because it was deprecated early in LFS
+  development.
+- When SSH is set as a remote, Git LFS objects still go through HTTPS.
+- Any Git LFS request asks for HTTPS credentials to be provided so a good Git
+  credentials store is recommended.
+- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must
+  [add the URL to Git configuration manually](#troubleshooting).
 
 NOTE:
 With 8.12 GitLab added LFS support to SSH. The Git LFS communication
 still goes over HTTP, but now the SSH client passes the correct credentials
-to the Git LFS client, so no action is required by the user.
+to the Git LFS client. No action is required by the user.
 
 ## Using Git LFS
 
@@ -60,8 +60,8 @@ git lfs install                       # initialize the Git LFS project
 git lfs track "*.iso"                 # select the file extensions that you want to treat as large files
 ```
 
-Once a certain file extension is marked for tracking as a LFS object you can use
-Git as usual without having to redo the command to track a file with the same extension:
+After you mark a file extension for tracking as a LFS object you can use
+Git as usual without redoing the command to track a file with the same extension:
 
 ```shell
 cp ~/tmp/debian.iso ./                # copy a large file into the current directory
@@ -71,7 +71,7 @@ git push origin master                # sync the git repo and large file to the
 ```
 
 **Make sure** that `.gitattributes` is tracked by Git. Otherwise Git
-LFS will not be working properly for people cloning the project:
+LFS doesn't work properly for people cloning the project:
 
 ```shell
 git add .gitattributes
@@ -93,8 +93,8 @@ that are on the remote repository, such as for a branch from origin:
 git lfs fetch origin master
 ```
 
-Make sure your files aren't listed in `.gitignore`, otherwise, they will be ignored by Git thus will not
-be pushed to the remote repository.
+Make sure your files aren't listed in `.gitignore`, otherwise, they are ignored by Git
+and are not pushed to the remote repository.
 
 ### Migrate an existing repository to Git LFS
 
@@ -178,7 +178,7 @@ available to the project anymore. Probably the object was removed from the serve
 
 ### Invalid status for `<url>` : 501
 
-Git LFS will log the failures into a log file.
+Git LFS logs the failures into a log file.
 To view this log file, while in project directory:
 
 ```shell
@@ -201,12 +201,19 @@ If the status `error 501` is shown, it is because:
   remove the line and try to update your Git LFS client. Only version 1.0.1 and
   newer are supported.
 
+<!-- vale gitlab.Spelling = NO -->
+
 ### getsockopt: connection refused
 
-If you push a LFS object to a project and you receive an error similar to:
-`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
+<!-- vale gitlab.Spelling = YES -->
+
+If you push an LFS object to a project and receive an error like this,
 the LFS client is trying to reach GitLab through HTTPS. However, your GitLab
-instance is being served on HTTP.
+instance is being served on HTTP:
+
+```plaintext
+Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused
+```
 
 This behavior is caused by Git LFS using HTTPS connections by default when a
 `lfsurl` is not set in the Git configuration.
@@ -222,10 +229,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"
 NOTE:
 With 8.12 GitLab added LFS support to SSH. The Git LFS communication
 still goes over HTTP, but now the SSH client passes the correct credentials
-to the Git LFS client, so no action is required by the user.
+to the Git LFS client. No action is required by the user.
 
-Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing
-the LFS object on every push for every object, user HTTPS credentials are required.
+Git LFS authenticates the user with HTTP Basic Authentication on every push for
+every object, so user HTTPS credentials are required.
 
 By default, Git has support for remembering the credentials for each repository
 you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials).
@@ -237,7 +244,7 @@ which you expect to push the objects:
 git config --global credential.helper 'cache --timeout=3600'
 ```
 
-This will remember the credentials for an hour after which Git operations will
+This remembers the credentials for an hour, after which Git operations
 require re-authentication.
 
 If you are using OS X you can use `osxkeychain` to store and encrypt your credentials.
@@ -258,7 +265,7 @@ If you are storing LFS files outside of GitLab you can disable LFS on the projec
 
 It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`.
 
-You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store,
-GitLab will not be able to verify LFS objects which means that pushes will fail if you have GitLab LFS support enabled.
+You might choose to do this if you are using an appliance like a <!-- vale gitlab.Spelling = NO --> Sonatype Nexus <!-- vale gitlab.Spelling = YES --> to store LFS data. If you choose to use an external LFS store,
+GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled.
 
-To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md). This means you will lose GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS).
+To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS).

doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md

@@ -37,9 +37,9 @@ ones that GitLab developed.
 
 ## Migration steps
 
-Since Git Annex files are stored in a sub-directory of the normal repositories
-(`.git/annex/objects`) and LFS files are stored outside of the repositories,
-they are not compatible as they are using a different scheme. Therefore, the
+Git Annex files are stored in a sub-directory of the normal repositories
+(`.git/annex/objects`) and LFS files are stored outside of the repositories.
+The two aren't compatible as they are using a different scheme. Therefore, the
 migration has to be done manually per repository.
 
 There are basically two steps you need to take in order to migrate from Git
@@ -74,17 +74,17 @@ Fire up a terminal, navigate to your Git repository and:
 ### Disabling Git Annex in your repository
 
 Before changing anything, make sure you have a backup of your repository first.
-There are a couple of ways to do that, but you can simply clone it to another
+There are a couple of ways to do that, but you can clone it to another
 local path and maybe push it to GitLab if you want a remote backup as well.
-Here you'll find a guide on
-[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive).
+A guide on
+[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive) is also available.
 
-Since Annex files are stored as objects with symlinks and cannot be directly
+Because Annex files are stored as objects with symlinks and cannot be directly
 modified, we need to first remove those symlinks.
 
 NOTE:
 Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains
-useful information that may fit in your use case. Note that `annex direct` is
+information that may fit in your use case. The `annex direct` command is
 deprecated in Git Annex version 6, so you may need to upgrade your repository
 if the server also has Git Annex 6 installed. Read more in the
 [Git Annex troubleshooting tips](../../../administration/git_annex.md#troubleshooting-tips) section.
@@ -133,7 +133,7 @@ if the server also has Git Annex 6 installed. Read more in the
    Deleted branch git-annex (was 2534d2c).
    ```
 
-   This will `unannex` every file in the repository, leaving the original files.
+   This command runs `unannex` on every file in the repository, leaving the original files.
 
 1. Switch back to `indirect` mode:
 
@@ -161,7 +161,7 @@ if the server also has Git Annex 6 installed. Read more in the
 ---
 
 At this point, you have two options. Either add, commit and push the files
-directly back to GitLab or switch to Git LFS. We will tackle the LFS switch in
+directly back to GitLab or switch to Git LFS. The LFS switch is described in
 the next section.
 
 ### Enabling Git LFS in your repository
@@ -194,7 +194,7 @@ GitLab.com), therefore, you don't need to do anything server-side.
    git lfs track images/         # per directory
    ```
 
-   Once you do that, run `git status` and you'll see `.gitattributes` added
+   After this, run `git status` to see the `.gitattributes` added
    to your repository. It collects all file patterns that you chose to track via
    `git-lfs`.
 
@@ -206,7 +206,7 @@ GitLab.com), therefore, you don't need to do anything server-side.
    git push
    ```
 
-   If your remote is set up with HTTP, you will be asked to enter your login
+   If your remote is set up with HTTP, you are asked to enter your login
    credentials. If you have [2FA enabled](../../../user/profile/account/two_factor_authentication.md), make sure to use a
    [personal access token](../../../user/profile/account/two_factor_authentication.md#personal-access-tokens)
    instead of your password.
@@ -244,5 +244,5 @@ git annex uninit
 - (Blog Post) [Getting Started with Git FLS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/)
 - (Blog Post) [Announcing LFS Support in GitLab](https://about.gitlab.com/blog/2015/11/23/announcing-git-lfs-support-in-gitlab/)
 - (Blog Post) [GitLab Annex Solves the Problem of Versioning Large Binaries with Git](https://about.gitlab.com/blog/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/)
-- (GitLab Docs) [Git Annex](../../../administration/git_annex.md)
-- (GitLab Docs) [Git LFS](index.md)
+- [Git Annex](../../../administration/git_annex.md)
+- [Git LFS](index.md)

doc/topics/git/useful_git_commands.md

@@ -7,8 +7,8 @@ type: reference
 
 # Useful Git commands
 
-Here are some useful Git commands collected by the GitLab support team. You may not
-need to use often, but they can come in handy when needed.
+The GitLab support team has collected these commands to help you. You may not
+need to use them often.
 
 ## Remotes
 
@@ -182,7 +182,7 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s
 
 ### Rebase your branch onto master
 
-The -i flag stands for 'interactive':
+The `-i` flag stands for 'interactive':
 
 ```shell
 git rebase -i master