summaryrefslogtreecommitdiff
path: root/doc/gitlab-basics
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gitlab-basics')
-rw-r--r--doc/gitlab-basics/README.md2
-rw-r--r--doc/gitlab-basics/add-file.md15
-rw-r--r--doc/gitlab-basics/create-branch.md6
-rw-r--r--doc/gitlab-basics/create-project.md30
-rw-r--r--doc/gitlab-basics/start-using-git.md21
5 files changed, 44 insertions, 30 deletions
diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md
index a7f18e13f74..3850655aaed 100644
--- a/doc/gitlab-basics/README.md
+++ b/doc/gitlab-basics/README.md
@@ -31,7 +31,7 @@ The following are guides to basic GitLab functionality:
- [Add a file](add-file.md), to add new files to a project's repository.
- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue),
to start collaborating within a project.
-- [Create a merge request](add-merge-request.md), to request changes made in a branch
+- [Create a merge request](../user/project/merge_requests/creating_merge_requests.md), to request changes made in a branch
be merged into a project's repository.
- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE)
and [GitLab Flow page](../topics/gitlab_flow.md).
diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md
index c5b57d4623d..0b400d7fdb4 100644
--- a/doc/gitlab-basics/add-file.md
+++ b/doc/gitlab-basics/add-file.md
@@ -29,16 +29,17 @@ to the desired destination:
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),
+[Create a new branch](create-branch.md) to add your file into. Submitting changes directly
+to the default branch should be avoided unless your project is very small and you're the
+only person working on it.
+
+You can also [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.
+on 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,
+Check if your file is actually present in the directory (if you're on Windows,
use `dir` instead):
```shell
@@ -79,7 +80,7 @@ Now you can push (send) your changes (in the branch `<branch-name>`) to GitLab
git push origin <branch-name>
```
-Your image will be added to your branch in your repository in GitLab.
+Your image is added to your branch in your repository in GitLab.
<!-- ## Troubleshooting
diff --git a/doc/gitlab-basics/create-branch.md b/doc/gitlab-basics/create-branch.md
index 0ad5cb53e97..9e51a2749a6 100644
--- a/doc/gitlab-basics/create-branch.md
+++ b/doc/gitlab-basics/create-branch.md
@@ -9,11 +9,11 @@ type: howto
A branch is an independent line of development in a [project](../user/project/index.md).
-When you create a new branch (in your [terminal](basic-git-commands.md) or with
+When you create a new branch (in your [terminal](start-using-git.md) or with
[the web interface](../user/project/repository/web_editor.md#create-a-new-branch)),
you are creating a snapshot of a certain branch, usually the main `master` branch,
-at it's current state. From there, you can start to make your own changes without
+at its current state. From there, you can start to make your own changes without
affecting the main codebase. The history of your changes will be tracked in your branch.
When your changes are ready, you then merge them into the rest of the codebase with a
-[merge request](add-merge-request.md).
+[merge request](../user/project/merge_requests/creating_merge_requests.md).
diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md
index f411ac769c0..616bb752694 100644
--- a/doc/gitlab-basics/create-project.md
+++ b/doc/gitlab-basics/create-project.md
@@ -18,13 +18,13 @@ To create a project in GitLab:
icon in the navigation bar. This opens the **New project** page.
1. On the **New project** page, choose if you want to:
- Create a [blank project](#blank-projects).
- - Create a project using with one of the available [project templates](#project-templates).
+ - Create a project using one of the available [project templates](#project-templates).
- [Import a project](../user/project/import/index.md) from a different repository,
- if enabled on your GitLab instance. Contact your GitLab admin if this is unavailable.
+ if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable.
- Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
NOTE: **Note:**
-For a list of words that cannot be used as project names see
+For a list of words that can't be used as project names see
[Reserved project and group names](../user/reserved_names.md).
### Blank projects
@@ -33,17 +33,17 @@ To create a new blank project on the **New project** page:
1. On the **Blank project** tab, provide the following information:
- The name of your project in the **Project name** field. You can't use
- special characters, but you can use spaces, hyphens, underscores or even
- emoji. When adding the name, the **Project slug** will auto populate.
- The slug is what the GitLab instance will use as the URL path to the project.
+ special characters, but you can use spaces, hyphens, underscores, or even
+ emoji. When adding the name, the **Project slug** auto populates.
+ The slug is what the GitLab instance uses as the URL path to the project.
If you want a different slug, input the project name first,
then change the slug after.
- The path to your project in the **Project slug** field. This is the URL
- path for your project that the GitLab instance will use. If the
- **Project name** is blank, it will auto populate when you fill in
+ path for your project that the GitLab instance uses. If the
+ **Project name** is blank, it auto populates when you fill in
the **Project slug**.
- The **Project description (optional)** field enables you to enter a
- description for your project's dashboard, which will help others
+ description for your project's dashboard, which helps others
understand what your project is about. Though it's not required, it's a good
idea to fill this in.
- Changing the **Visibility Level** modifies the project's
@@ -58,7 +58,7 @@ To create a new blank project on the **New project** page:
Project templates can pre-populate a new project with the necessary files to get you
started quickly.
-There are two types of project templates:
+There are two main types of project templates:
- [Built-in templates](#built-in-templates), sourced from the following groups:
- [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
@@ -128,11 +128,11 @@ To use a custom project template on the **New project** page:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5.
-When you create a new repository locally, instead of going to GitLab to manually
-create a new project and then [clone the repo](start-using-git.md#clone-a-repository)
+When you create a new repository locally, instead of manually creating a new project in GitLab
+and then [cloning the repository](start-using-git.md#clone-a-repository)
locally, you can directly push it to GitLab to create the new project, all without leaving
-your terminal. If you have access rights to the associated namespace, GitLab will
-automatically create a new project under that GitLab namespace with its visibility
+your terminal. If you have access rights to the associated namespace, GitLab
+automatically creates a new project under that GitLab namespace with its visibility
set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
This can be done by using either SSH or HTTPS:
@@ -145,7 +145,7 @@ git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git
git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master
```
-Once the push finishes successfully, a remote message will indicate
+Once the push finishes successfully, a remote message indicates
the command to set the remote and the URL to the new project:
```plaintext
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index 3812fd3b92a..b6192700d29 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -323,19 +323,25 @@ to work on a different **branch**.
When you create a branch in a Git repository, you make a copy of its files at the time of branching. You're free
to do whatever you want with the code in your branch without impacting the main branch or other branches. And when
-you're ready to bring your changes to the main codebase, you can merge your branch into the main one
+you're ready to bring your changes to the main codebase, you can merge your branch into the default branch
used in your project (such as `master`).
+A new branch is often called **feature branch** to differentiate from the
+**default branch**.
+
### Create a branch
-To create a new branch, to work from without affecting the `master` branch, type
-the following (spaces won't be recognized in the branch name, so you will need to
-use a hyphen or underscore):
+To create a new feature branch and work from without affecting the `master`
+branch:
```shell
git checkout -b <name-of-branch>
```
+Note that Git does **not** accept empty spaces and special characters in branch
+names, so use only lowercase letters, numbers, hyphens (`-`), and underscores
+(`_`). Do not use capital letters, as it may cause duplications.
+
### Switch to the master branch
You are always in a branch when working with Git. The main branch is the master
@@ -411,6 +417,9 @@ For example, to push your local commits to the _`master`_ branch of the _`origin
git push origin master
```
+On certain occasions, Git won't allow you to push to your repository, and then
+you'll need to [force an update](../topics/git/git_rebase.md#force-push).
+
NOTE: **Note:**
To create a merge request from a fork to an upstream repository, see the
[forking workflow](../user/project/repository/forking_workflow.md).
@@ -459,6 +468,10 @@ git checkout <name-of-branch>
git merge master
```
+## Advanced use of Git through the command line
+
+For an introduction of more advanced Git techniques, see [Git rebase, force-push, and merge conflicts](../topics/git/git_rebase.md).
+
## Synchronize changes in a forked repository with the upstream
[Forking a repository](../user/project/repository/forking_workflow.md) lets you create