diff options
Diffstat (limited to 'doc/topics/git')
-rw-r--r-- | doc/topics/git/feature_branch_development.md | 86 | ||||
-rw-r--r-- | doc/topics/git/img/create_merge_request_v13_1.png | bin | 0 -> 16387 bytes | |||
-rw-r--r-- | doc/topics/git/img/modify_branches_v13_1.png | bin | 0 -> 75159 bytes | |||
-rw-r--r-- | doc/topics/git/index.md | 3 | ||||
-rw-r--r-- | doc/topics/git/lfs/index.md | 20 | ||||
-rw-r--r-- | doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md | 6 | ||||
-rw-r--r-- | doc/topics/git/lfs/migrate_to_git_lfs.md | 12 | ||||
-rw-r--r-- | doc/topics/git/numerous_undo_possibilities_in_git/index.md | 5 | ||||
-rw-r--r-- | doc/topics/git/partial_clone.md | 4 |
9 files changed, 114 insertions, 22 deletions
diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md new file mode 100644 index 00000000000..ab3adf54dd7 --- /dev/null +++ b/doc/topics/git/feature_branch_development.md @@ -0,0 +1,86 @@ +--- +type: how-tos +--- + +# Develop on a feature branch + +GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc). +However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch. +People can contribute MRs to that feature branch, without affecting the functionality of the default (usually `master`) branch. + +Once work on the development branch is complete, then the feature branch can be finally merged into the default branch. + +GitLab frequently implements this process whenever there is an MVC that requires multiple MRs. + +## Use case: GitLab's release posts + +This section describes the use case with GitLab [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/). +Dozens of GitLab team members contribute to each monthly release post. +In such cases, it may be more efficient to submit an MR on the release post feature branch instead of master. + +In this case, the feature branch would be `release-X-Y`. Assuming the `release-X-Y` branch already exists, you can set up an MR against that branch, with the following steps: + +1. Create a new branch (`test-branch`) against the feature branch (`release-X-Y`): + + ```shell + git checkout -b test-branch release-X-Y + ``` + + You should now be on a branch named `test-branch`. + +1. Make desired changes on the `test-branch`. +1. Add your changes, commit, and push to the `test-branch`: + + ```shell + git add . + ``` + +1. Commit your changes: + + ```shell + git commit -m "Some good reason" + ``` + +1. Push your changes to the repository: + + ```shell + git push --set-upstream origin test-branch + ``` + +1. Navigate to the URL for your repository. In this case, the repository is `www-gitlab-com`, available at `https://gitlab.com/gitlab-com/www-gitlab-com`. + + If needed, sign in to GitLab. You should then see an option to **Create merge request**: + + ![Create merge request](img/create_merge_request_v13_1.png) + +1. After you click **Create merge request**, you'll see an option to **Change branches**. Select that option. + +1. In the **New Merge Request** screen, you can now select the **Source** and **Target** branches. +In the screenshot shown, +we have selected `test-branch` as the source, and `release-13-0` as the target. + + ![Modify branches](img/modify_branches_v13_1.png) + +1. Once you've selected the Source and Target branches, click **Compare branches and continue**. + You should see an entry similar to: + + ```plaintext + New Merge Request + + From test-branch into release-13-0 + ``` + + An entry like this confirms that your MR will **not** merge into master. + +1. Make any additional changes in the **New Merge Request** screen, and click **Submit merge request**. +1. In the new merge request, look for **Request to merge**. You'll see an entry similar to: + + ```plaintext + Request to merge test-branch into release-13-0 + ``` + + That confirms you've set up the MR to merge into the specified branch, not master. + +1. Proceed with the change as you would with any other MR. +1. When your MR is approved, and an appropriate user merges that MR, you can rest assured that your work is incorporated directly into the feature branch. +When the feature branch is ready, it can then be merged into master. diff --git a/doc/topics/git/img/create_merge_request_v13_1.png b/doc/topics/git/img/create_merge_request_v13_1.png Binary files differnew file mode 100644 index 00000000000..a725149f6a2 --- /dev/null +++ b/doc/topics/git/img/create_merge_request_v13_1.png diff --git a/doc/topics/git/img/modify_branches_v13_1.png b/doc/topics/git/img/modify_branches_v13_1.png Binary files differnew file mode 100644 index 00000000000..dc517dd249f --- /dev/null +++ b/doc/topics/git/img/modify_branches_v13_1.png diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index 9e6875312f3..2e36fea14bf 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -68,6 +68,7 @@ If you have problems with Git, the following may help: ## Branching strategies - [Feature branch workflow](../../gitlab-basics/feature_branch_workflow.md) +- [Develop on a feature branch](feature_branch_development.md) - [GitLab Flow](../gitlab_flow.md) - [Git Branching - Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) - [Git Branching - Branching Workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows) @@ -91,7 +92,7 @@ Git-related queries from GitLab. The following relate to Git Large File Storage: - [Getting Started with Git LFS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) -- [Migrate an existing Git repo with Git LFS](lfs/migrate_to_git_lfs.md) +- [Migrate an existing Git repository with Git LFS](lfs/migrate_to_git_lfs.md) - [Removing objects from LFS](lfs/index.md#removing-objects-from-lfs) - [GitLab Git LFS user documentation](lfs/index.md) - [GitLab Git LFS admin documentation](../../administration/lfs/index.md) diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 33b7fa45691..706d3c3eddf 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -37,7 +37,7 @@ Documentation for GitLab instance administrators is under [LFS administration do - 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 config manually (see [troubleshooting](#troubleshooting)) + to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) NOTE: **Note:** With 8.12 GitLab added LFS support to SSH. The Git LFS communication @@ -83,7 +83,7 @@ git clone git@gitlab.example.com:group/project.git ``` If you already cloned the repository and you want to get the latest LFS object -that are on the remote repository, eg. for a branch from origin: +that are on the remote repository, such as for a branch from origin: ```shell git lfs fetch origin master @@ -91,18 +91,18 @@ git lfs fetch origin master ### Migrate an existing repo to Git LFS -Read the documentation on how to [migrate an existing Git repo with Git LFS](migrate_to_git_lfs.md). +Read the documentation on how to [migrate an existing Git repository with Git LFS](migrate_to_git_lfs.md). ### Removing objects from LFS To remove objects from LFS: -1. Use [BFG-Cleaner](../../../user/project/repository/reducing_the_repo_size_using_git.md#using-the-bfg-repo-cleaner) or [filter-branch](../../../user/project/repository/reducing_the_repo_size_using_git.md#using-git-filter-branch) to remove the objects from the repository. +1. Use [`git filter-repo`](../../../user/project/repository/reducing_the_repo_size_using_git.md) to remove the objects from the repository. 1. Delete the relevant LFS lines for the objects you have removed from your `.gitattributes` file and commit those changes. ## File Locking -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/35856) in GitLab 10.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. The first thing to do before using File Locking is to tell Git LFS which kind of files are lockable. The following command will store PNG files @@ -128,7 +128,7 @@ in order to do that you can edit the `.gitattributes` file manually: ``` After a file type has been registered as lockable, Git LFS will make -them readonly on the file system automatically. This means you will +them read-only on the file system automatically. This means you will need to lock the file before editing it. ### Managing Locked Files @@ -205,8 +205,8 @@ If the status `error 501` is shown, it is because: on how to enable LFS support. - Git LFS client version is not supported by GitLab server. Check your Git LFS - version with `git lfs version`. Check the Git config of the project for traces - of deprecated API with `git lfs -l`. If `batch = false` is set in the config, + version with `git lfs version`. Check the Git configuration of the project for traces + of deprecated API with `git lfs -l`. If `batch = false` is set in the configuration, remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported. @@ -218,9 +218,9 @@ the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP. This behavior is caused by Git LFS using HTTPS connections by default when a -`lfsurl` is not set in the Git config. +`lfsurl` is not set in the Git configuration. -To prevent this from happening, set the lfs URL in project Git config: +To prevent this from happening, set the LFS URL in project Git configuration: ```shell git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md index 05b749d7b24..09087fcae13 100644 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md @@ -1,7 +1,7 @@ # Migration guide from Git Annex to Git LFS >**Note:** -Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/issues/1648) in GitLab Enterprise +Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise Edition 9.0 (2017/03/22). Both [Git Annex](http://git-annex.branchable.com/) and [Git LFS](https://git-lfs.github.com/) are tools to manage large files in Git. @@ -172,7 +172,7 @@ GitLab.com), therefore, you don't need to do anything server-side. If the terminal doesn't prompt you with a full response on `git-lfs` commands, [install the Git LFS client](https://git-lfs.github.com/) first. -1. Inside the repo, run the following command to initiate LFS: +1. Inside the repository, run the following command to initiate LFS: ```shell git lfs install @@ -189,7 +189,7 @@ GitLab.com), therefore, you don't need to do anything server-side. ``` Once you do that, run `git status` and you'll see `.gitattributes` added - to your repo. It collects all file patterns that you chose to track via + to your repository. It collects all file patterns that you chose to track via `git-lfs`. 1. Add the files, commit and push them to GitLab: diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 60859686047..a64639a9238 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -16,18 +16,18 @@ the files are still referenced by previous commits. Through the method described on this document, first migrate to Git LFS with a tool such as the open source community-maintained [BFG](https://rtyley.github.io/bfg-repo-cleaner/) -through a mirror repo, then clean up the repository's history, +through a mirror repository, then clean up the repository's history, and lastly create LFS tracking rules to prevent new binary files from being added. This tutorial was inspired by the guide -[Use BFG to migrate a repo to Git LFS](https://confluence.atlassian.com/bitbucket/use-bfg-to-migrate-a-repo-to-git-lfs-834233484.html). +[Use BFG to migrate a repository to Git LFS](https://confluence.atlassian.com/bitbucket/use-bfg-to-migrate-a-repo-to-git-lfs-834233484.html). For more information on Git LFS, see the [references](#references) below. CAUTION: **Warning:** The method described on this guide rewrites Git history. Make -sure to back up your repo before beginning and use it at your +sure to back up your repository before beginning and use it at your own risk. ## Requirements @@ -71,7 +71,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- Create a copy of your repository so that you can recover it in case something goes wrong. -1. Clone `--mirror` the repo: +1. Clone `--mirror` the repository: Cloning with the mirror flag will create a bare repository. This ensures you get all the branches within the repo. @@ -102,7 +102,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- git reflog expire --expire=now --all && git gc --prune=now --aggressive ``` - You can also take a look on how to further [clean the repo](../../../user/project/repository/reducing_the_repo_size_using_git.md), + You can also take a look on how to further [clean the repository](../../../user/project/repository/reducing_the_repo_size_using_git.md), but it's not necessary for the purposes of this guide. 1. Install Git LFS in the mirror repository: @@ -166,7 +166,7 @@ but commented out to help encourage others to add to it in the future. --> - [Migrate from Git Annex to Git LFS](migrate_from_git_annex_to_git_lfs.md) - [GitLab's Git LFS user documentation](index.md) - [GitLab's Git LFS administrator documentation](../../../administration/lfs/index.md) -- Alternative method to [migrate an existing repo to Git LFS](https://github.com/git-lfs/git-lfs/wiki/Tutorial#migrating-existing-repository-data-to-lfs) +- Alternative method to [migrate an existing repository to Git LFS](https://github.com/git-lfs/git-lfs/wiki/Tutorial#migrating-existing-repository-data-to-lfs) <!-- Test project: diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 8597325db7b..fdf86d8f646 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -26,6 +26,11 @@ This means that until Git automatically cleans detached commits (which cannot be accessed by branch or tag) it will be possible to view them with `git reflog` command and access them with direct commit ID. Read more about _[redoing the undo](#redoing-the-undo)_ in the section below. +> For more information about working with Git and GitLab: +> +> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn why [North Western Mutual chose GitLab](https://youtu.be/kPNMyxKRRoM) for their Enterprise source code management. +> - Learn how to [get started with Git](https://about.gitlab.com/resources/whitepaper-moving-to-git/). + ## Introduction This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index 46318a7f30d..7462406cad3 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -141,7 +141,7 @@ enabled on the Git server: 1. **Create a new Git repository and fetch.** Support for `--filter=sparse:oid` using the clone command is incomplete, so we will emulate the clone command by hand, using `git init` and `git fetch`. Follow - [issue tracking support for `--filter=sparse:oid`](https://gitlab.com/gitlab-org/git/issues/4) + [issue tracking support for `--filter=sparse:oid`](https://gitlab.com/gitlab-org/git/-/issues/4) for updates. ```shell @@ -173,7 +173,7 @@ enabled on the Git server: 1. **Sparse checkout** must be enabled and configured to prevent objects from other paths being downloaded automatically when checking out branches. Follow - [issue proposing automating sparse checkouts](https://gitlab.com/gitlab-org/git/issues/5) for updates. + [issue proposing automating sparse checkouts](https://gitlab.com/gitlab-org/git/-/issues/5) for updates. ```shell # Enable sparse checkout |