Skip to content

G
gitlab-ce
Commit 15b9bc05 authored by Craig Norris's avatar Craig Norris
Browse files
Options

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

Word and line edits for Create documentation

See merge request gitlab-org/gitlab!52731
parents 1c9721c5 7b6b1841
Show whitespace changes
Inline Side-by-side
Showing with 144 additions and 130 deletions
doc/topics/git/git_rebase.md
View file @ 15b9bc05
...@@ -69,7 +69,7 @@ changes by resetting `my-feature-branch` against `my-feature-branch-backup`: ...@@ -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, 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 ### Regular rebase
...@@ -116,7 +116,7 @@ example, `release-10-3`. You can also replace `origin` with other remote ...@@ -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 repositories, for example, `upstream`. To check what remotes you have linked to your local
repository, you can run `git remote -v`. 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. them before continuing the rebase.
To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) 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) ...@@ -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 You can use interactive rebase to modify commits. For example, amend a commit
message, squash (join multiple commits into one), edit, or delete message, squash (join multiple commits into one), edit, or delete
commits. It is handy for changing past commit messages, commits. Use a rebase for changing past commit messages,
as well as for organizing the commit history of your branch to keep it clean. and organizing the commit history of your branch to keep it clean.
NOTE: NOTE:
If you want to keep the default branch commit history clean, you don't need to 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; manually squash all your commits before merging every merge request.
with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md) With [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md),
GitLab does it automatically. GitLab does it automatically.
When you want to change anything in recent commits, use interactive 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 ...@@ -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 a macOS's `ZSH` shell, and you want to **squash** all the three commits
(join them into one): (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 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. 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 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 ...@@ -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. Press <kbd>Escape</kbd> to leave the editing mode.
1. Type `:wq` to "write" (save) and "quit". 1. Type `:wq` to "write" (save) and "quit".
1. Git outputs the commit message so you have a chance to edit it: 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 - All lines starting with `#` are ignored and not included in the commit
message. Everything else will be included. message. Everything else is included.
- To leave it as it is, type `:wq`. To edit the commit message: switch to the - 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. 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, 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. ...@@ -180,8 +181,8 @@ for a deeper look into interactive rebase.
## Force-push ## Force-push
When you perform more complex operations, for example, squash commits, reset or 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, rebase your branch, you must _force_ an update to the remote branch.
since these operations imply rewriting the commit history of the 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 To force an update, pass the flag `--force` or `-f` to the `push` command. For
example: example:
...@@ -267,6 +268,6 @@ To fix conflicts locally, you can use the following method: ...@@ -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. 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 Git aborts the rebase and rolls back the branch to the state you had before
running `git rebase`. 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. 1. [Force-push](#force-push) to your remote branch.
doc/topics/git/lfs/index.md
View file @ 15b9bc05
...@@ -14,13 +14,13 @@ larger than 1GB to preserve performance. ...@@ -14,13 +14,13 @@ larger than 1GB to preserve performance.
![Git LFS tracking status](img/lfs-icon.png) ![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 Files tracked by Git LFS display an icon to indicate if the file is stored as a
as a blob or as an LFS pointer. blob or an LFS pointer.
## How it works ## How it works
Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication 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. instructions from where to fetch or where to push the large file.
## GitLab server configuration ## GitLab server configuration
...@@ -35,18 +35,18 @@ Documentation for GitLab instance administrators is under [LFS administration do ...@@ -35,18 +35,18 @@ Documentation for GitLab instance administrators is under [LFS administration do
## Known limitations ## Known limitations
- Git LFS v1 original API is not supported since it was deprecated early in LFS - Git LFS v1 original API is not supported, because it was deprecated early in LFS
development development.
- When SSH is set as a remote, Git LFS objects still go through HTTPS - 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 - Any Git LFS request asks for HTTPS credentials to be provided so a good Git
credentials store is recommended credentials store is recommended.
- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must
to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) [add the URL to Git configuration manually](#troubleshooting).
NOTE: NOTE:
With 8.12 GitLab added LFS support to SSH. The Git LFS communication 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 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 ## Using Git LFS
...@@ -60,8 +60,8 @@ git lfs install # initialize the Git LFS project ...@@ -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 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 After you mark a file extension 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: Git as usual without redoing the command to track a file with the same extension:
```shell ```shell
cp ~/tmp/debian.iso ./ # copy a large file into the current directory 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 ...@@ -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 **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 ```shell
git add .gitattributes git add .gitattributes
...@@ -93,8 +93,8 @@ that are on the remote repository, such as for a branch from origin: ...@@ -93,8 +93,8 @@ that are on the remote repository, such as for a branch from origin:
git lfs fetch origin master git lfs fetch origin master
``` ```
Make sure your files aren't listed in `.gitignore`, otherwise, they will be ignored by Git thus will not Make sure your files aren't listed in `.gitignore`, otherwise, they are ignored by Git
be pushed to the remote repository. and are not pushed to the remote repository.
### Migrate an existing repository to Git LFS ### Migrate an existing repository to Git LFS
...@@ -178,7 +178,7 @@ available to the project anymore. Probably the object was removed from the serve ...@@ -178,7 +178,7 @@ available to the project anymore. Probably the object was removed from the serve
### Invalid status for `<url>` : 501 ### 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: To view this log file, while in project directory:
```shell ```shell
...@@ -201,12 +201,19 @@ If the status `error 501` is shown, it is because: ...@@ -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 remove the line and try to update your Git LFS client. Only version 1.0.1 and
newer are supported. newer are supported.
<!-- vale gitlab.Spelling = NO -->
### getsockopt: connection refused ### getsockopt: connection refused
If you push a LFS object to a project and you receive an error similar to: <!-- vale gitlab.Spelling = YES -->
`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
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 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 This behavior is caused by Git LFS using HTTPS connections by default when a
`lfsurl` is not set in the Git configuration. `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" ...@@ -222,10 +229,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"
NOTE: NOTE:
With 8.12 GitLab added LFS support to SSH. The Git LFS communication 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 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 Git LFS authenticates the user with HTTP Basic Authentication on every push for
the LFS object on every push for every object, user HTTPS credentials are required. every object, so user HTTPS credentials are required.
By default, Git has support for remembering the credentials for each repository 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). 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: ...@@ -237,7 +244,7 @@ which you expect to push the objects:
git config --global credential.helper 'cache --timeout=3600' 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. require re-authentication.
If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. 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 ...@@ -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`. 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, 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 will not be able to verify LFS objects which means that pushes will fail if you have GitLab LFS support enabled. 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
View file @ 15b9bc05
...@@ -37,9 +37,9 @@ ones that GitLab developed. ...@@ -37,9 +37,9 @@ ones that GitLab developed.
## Migration steps ## Migration steps
Since Git Annex files are stored in a sub-directory of the normal repositories 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, (`.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 The two aren't compatible as they are using a different scheme. Therefore, the
migration has to be done manually per repository. migration has to be done manually per repository.
There are basically two steps you need to take in order to migrate from Git 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: ...@@ -74,17 +74,17 @@ Fire up a terminal, navigate to your Git repository and:
### Disabling Git Annex in your repository ### Disabling Git Annex in your repository
Before changing anything, make sure you have a backup of your repository first. 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. local path and maybe push it to GitLab if you want a remote backup as well.
Here you'll find a guide on 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). [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. modified, we need to first remove those symlinks.
NOTE: NOTE:
Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains 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 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 if the server also has Git Annex 6 installed. Read more in the
[Git Annex troubleshooting tips](../../../administration/git_annex.md#troubleshooting-tips) section. [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 ...@@ -133,7 +133,7 @@ if the server also has Git Annex 6 installed. Read more in the
Deleted branch git-annex (was 2534d2c). 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: 1. Switch back to `indirect` mode:
...@@ -161,7 +161,7 @@ if the server also has Git Annex 6 installed. Read more in the ...@@ -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 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. the next section.
### Enabling Git LFS in your repository ### Enabling Git LFS in your repository
...@@ -194,7 +194,7 @@ GitLab.com), therefore, you don't need to do anything server-side. ...@@ -194,7 +194,7 @@ GitLab.com), therefore, you don't need to do anything server-side.
git lfs track images/ # per directory 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 to your repository. It collects all file patterns that you chose to track via
`git-lfs`. `git-lfs`.
...@@ -206,7 +206,7 @@ GitLab.com), therefore, you don't need to do anything server-side. ...@@ -206,7 +206,7 @@ GitLab.com), therefore, you don't need to do anything server-side.
git push 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 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) [personal access token](../../../user/profile/account/two_factor_authentication.md#personal-access-tokens)
instead of your password. instead of your password.
...@@ -244,5 +244,5 @@ git annex uninit ...@@ -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) [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) [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/) - (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) - [Git Annex](../../../administration/git_annex.md)
- (GitLab Docs) [Git LFS](index.md) - [Git LFS](index.md)
doc/topics/git/numerous_undo_possibilities_in_git/index.md
View file @ 15b9bc05
...@@ -7,21 +7,19 @@ type: howto ...@@ -7,21 +7,19 @@ type: howto
# Numerous undo possibilities in Git # Numerous undo possibilities in Git
In this tutorial, we will show you different ways of undoing your work in Git, for which This tutorial shows you different ways of undoing your work in Git.
we will assume you have a basic working knowledge of. Check the GitLab We assume you have a basic working knowledge of Git. Check the GitLab
[Git documentation](../index.md) for reference. [Git documentation](../index.md) for reference.
Also, we will only provide some general information of the commands, which is enough We only provide some general information about the commands to get you started.
to get you started for the easy cases/examples, but for anything more advanced For more advanced examples, refer to the [Git book](https://git-scm.com/book/en/v2).
please refer to the [Git book](https://git-scm.com/book/en/v2).
We will explain a few different techniques to undo your changes based on the stage A few different techniques exist to undo your changes, based on the stage
of the change in your current development. Also, keep in mind that [nothing in of the change in your current development. Remember that
Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). [nothing in Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery).
Until Git cleans detached commits - commits that cannot be accessed by branch or tag -
This means that until Git automatically cleans detached commits (which cannot be you can view them with `git reflog` command, and access them with direct commit ID.
accessed by branch or tag) it will be possible to view them with `git reflog` command Read more about [redoing the undo](#redoing-the-undo) in the section below.
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: > For more information about working with Git and GitLab:
> >
...@@ -30,13 +28,16 @@ and access them with direct commit ID. Read more about _[redoing the undo](#redo ...@@ -30,13 +28,16 @@ and access them with direct commit ID. Read more about _[redoing the undo](#redo
## Introduction ## 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) This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository):
where you want to undo your changes from and if they were shared with other developers
or not. Because Git is tracking changes a created or edited file is in the unstaged state - Where do you want to undo your changes from?
- Were they shared with other developers?
Because Git tracks changes, a created or edited file is in the unstaged state
(if created it is untracked by Git). After you add it to a repository (`git add`) you put (if created it is untracked by Git). After you add it to a repository (`git add`) you put
a file into the **staged** state, which is then committed (`git commit`) to your a file into the **staged** state, which is then committed (`git commit`) to your
local repository. After that, file can be shared with other developers (`git push`). local repository. After that, file can be shared with other developers (`git push`).
Here's what we'll cover in this tutorial: This tutorial covers:
- [Undo local changes](#undo-local-changes) which were not pushed to a remote repository: - [Undo local changes](#undo-local-changes) which were not pushed to a remote repository:
...@@ -54,38 +55,38 @@ Here's what we'll cover in this tutorial: ...@@ -54,38 +55,38 @@ Here's what we'll cover in this tutorial:
### Branching strategy ### Branching strategy
[Git](https://git-scm.com/) is a de-centralized version control system, which means that beside regular [Git](https://git-scm.com/) is a de-centralized version control system. Beside regular
versioning of the whole repository, it has possibilities to exchange changes versioning of the whole repository, it has possibilities to exchange changes
with other repositories. with other repositories.
To avoid chaos with To avoid chaos with
[multiple sources of truth](https://git-scm.com/about/distributed), various [multiple sources of truth](https://git-scm.com/about/distributed), various
development workflows have to be followed, and it depends on your internal development workflows have to be followed. It depends on your internal
workflow how certain changes or commits can be undone or changed. workflow how certain changes or commits can be undone or changed.
[GitLab Flow](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) provides a good [GitLab Flow](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) provides a good
balance between developers clashing with each other while balance between developers clashing with each other while
developing the same feature and cooperating seamlessly, but it does not enable developing the same feature and cooperating seamlessly. However, it does not enable
joined development of the same feature by multiple developers by default. joined development of the same feature by multiple developers by default.
When multiple developers develop the same feature on the same branch, clashing When multiple developers develop the same feature on the same branch, clashing
with every synchronization is unavoidable, but a proper or chosen Git Workflow will with every synchronization is unavoidable. However, a proper or chosen Git Workflow
prevent that anything is lost or out of sync when the feature is complete. prevents lost or out-of-sync data when the feature is complete.
You can also You can also
read through this blog post on [Git Tips & Tricks](https://about.gitlab.com/blog/2016/12/08/git-tips-and-tricks/) read through this blog post on [Git Tips & Tricks](https://about.gitlab.com/blog/2016/12/08/git-tips-and-tricks/)
to learn how to easily **do** things in Git. to learn how to do things in Git.
## Undo local changes ## Undo local changes
Until you push your changes to any remote repository, they will only affect you. Until you push your changes to any remote repository, they only affect you.
That broadens your options on how to handle undoing them. Still, local changes That broadens your options on how to handle undoing them. Still, local changes
can be on various stages and each stage has a different approach on how to tackle them. can be on various stages and each stage has a different approach on how to tackle them.
### Unstaged local changes (before you commit) ### Unstaged local changes (before you commit)
When a change is made, but it is not added to the staged tree, Git itself When a change is made, but not added to the staged tree, Git
proposes a solution to discard changes to a certain file. proposes a solution to discard changes to the file.
Suppose you edited a file to change the content using your favorite editor: Suppose you edited a file to change the content using your favorite editor:
...@@ -93,7 +94,7 @@ Suppose you edited a file to change the content using your favorite editor: ...@@ -93,7 +94,7 @@ Suppose you edited a file to change the content using your favorite editor:
vim <file> vim <file>
``` ```
Since you did not `git add <file>` to staging, it should be under unstaged files (or Because you did not `git add <file>` to staging, it should be under unstaged files (or
untracked if file was created). You can confirm that with: untracked if file was created). You can confirm that with:
```shell ```shell
...@@ -136,32 +137,37 @@ you would like to apply them at some later time. You can read more about it in ...@@ -136,32 +137,37 @@ you would like to apply them at some later time. You can read more about it in
### Quickly save local changes ### Quickly save local changes
You are working on a feature when a boss drops by with an urgent task. Since your You are working on a feature when a boss drops by with an urgent task. Because your
feature is not complete, but you need to swap to another branch, you can use feature is not complete, but you need to swap to another branch, you can use
`git stash` to save what you had done, swap to another branch, commit, push, `git stash` to:
test, then get back to previous feature branch, do `git stash pop` and continue
where you left. - Save what you have done.
- Swap to another branch.
- Commit, push, and test.
- Return to the feature branch.
- Run `git stash pop`.
- Resume your work.
The example above shows that discarding all changes is not always a preferred option, The example above shows that discarding all changes is not always a preferred option.
but Git provides a way to save them for later, while resetting the repository to state without However, Git provides a way to save them for later, while resetting the repository to state without
them. This is achieved by Git stashing command `git stash`, which in fact saves your them. This is achieved by Git stashing command `git stash`, which in fact saves your
current work and runs `git reset --hard`, but it also has various current work and runs `git reset --hard`, but it also has various
additional options like: additional options like:
- `git stash save`, which enables including temporary commit message, which will help you identify changes, among with other options - `git stash save`, which enables including temporary commit message, which helps you identify changes, among with other options
- `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed - `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed
- `git stash pop`, which redoes previously stashed changes and removes them from stashed list - `git stash pop`, which redoes previously stashed changes and removes them from stashed list
- `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list - `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list
### Staged local changes (before you commit) ### Staged local changes (before you commit)
Let's say you have added some files to staging, but you want to remove them from the If you add some files to staging, but you want to remove them from the
current commit, yet you want to retain those changes - just move them outside current commit while retaining those changes, move them outside
of the staging tree. You also have an option to discard all changes with of the staging tree. You can also discard all changes with
`git reset --hard` or think about `git stash` [as described earlier.](#quickly-save-local-changes) `git reset --hard` or think about `git stash` [as described earlier.](#quickly-save-local-changes)
Lets start the example by editing a file, with your favorite editor, to change the Lets start the example by editing a file with your favorite editor to change the
content and add it to staging content and add it to staging:
```shell ```shell
vim <file> vim <file>
...@@ -208,17 +214,17 @@ Now you have 4 options to undo your changes: ...@@ -208,17 +214,17 @@ Now you have 4 options to undo your changes:
## Committed local changes ## Committed local changes
Once you commit, your changes are recorded by the version control system. After you commit, your changes are recorded by the version control system.
Because you haven't pushed to your remote repository yet, your changes are Because you haven't pushed to your remote repository yet, your changes are
still not public (or shared with other developers). At this point, undoing still not public (or shared with other developers). At this point, undoing
things is a lot easier, we have quite some workaround options. Once you push things is a lot easier, we have quite some workaround options. After you push
your code, you'll have less options to troubleshoot your work. your code, you have fewer options to troubleshoot your work.
### Without modifying history ### Without modifying history
Through the development process some of the previously committed changes do not Through the development process some of the previously committed changes do not
fit anymore in the end solution, or are source of the bugs. Once you find the fit anymore in the end solution, or are source of the bugs. After you find the
commit which triggered bug, or once you have a faulty commit, you can simply commit which triggered bug, or identify a faulty commit, you can
revert it with `git revert commit-id`. revert it with `git revert commit-id`.
This command inverts (swaps) the additions and This command inverts (swaps) the additions and
...@@ -226,19 +232,19 @@ deletions in that commit, so that it does not modify history. Retaining history ...@@ -226,19 +232,19 @@ deletions in that commit, so that it does not modify history. Retaining history
can be helpful in future to notice that some changes have been tried can be helpful in future to notice that some changes have been tried
unsuccessfully in the past. unsuccessfully in the past.
In our example we will assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`, In our example we assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`,
and `B` is the commit you want to undo. There are many different ways to identify commit and `B` is the commit you want to undo. There are many different ways to identify commit
`B` as bad, one of them is to pass a range to `git bisect` command. The provided range includes `B` as bad. One of them is to pass a range to `git bisect` command. The provided range includes
last known good commit (we assume `A`) and first known bad commit (where bug was detected - we will assume `E`). last known good commit (we assume `A`) and first known bad commit where the bug was detected (we assume `E`).
```shell ```shell
git bisect A..E git bisect A..E
``` ```
Bisect will provide us with commit ID of the middle commit to test, and then guide us Bisect provides us with commit ID of the middle commit to test, and then guide us
through simple bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git) through the bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git)
In our example we will end up with commit `B`, that introduced the bug/error. We have Our example results in commit `B`, which introduced the bug/error. We have
4 options on how to remove it (or part of it) from our repository. these options to remove all or part of it from our repository:
- Undo (swap additions and deletions) changes introduced by commit `B`: - Undo (swap additions and deletions) changes introduced by commit `B`:
...@@ -260,13 +266,13 @@ In our example we will end up with commit `B`, that introduced the bug/error. We ...@@ -260,13 +266,13 @@ In our example we will end up with commit `B`, that introduced the bug/error. We
- There is one command we also must not forget: **creating a new branch** - There is one command we also must not forget: **creating a new branch**
from the point where changes are not applicable or where the development has hit a from the point where changes are not applicable or where the development has hit a
dead end. For example you have done commits `A-B-C-D` on your feature-branch dead end. For example you have done commits `A-B-C-D` on your feature branch
and then you figure `C` and `D` are wrong. and then you figure `C` and `D` are wrong.
At this point you either reset to `B` At this point you either reset to `B`
and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) and do commit `F` (which causes problems with pushing and if forced pushed also with other developers)
since branch now looks `A-B-F`, which clashes with what other developers have locally (you will because the branch now looks `A-B-F`, which clashes with what other developers have locally (you will
[change history](#with-history-modification)), or you simply checkout commit `B` create [change history](#with-history-modification)), or you checkout commit `B` create
a new branch and do commit `F`. In the last case, everyone else can still do their work while you a new branch and do commit `F`. In the last case, everyone else can still do their work while you
have your new way to get it right and merge it back in later. Alternatively, with GitLab, have your new way to get it right and merge it back in later. Alternatively, with GitLab,
you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
...@@ -291,7 +297,7 @@ provides interactive mode (`-i` flag) which enables you to: ...@@ -291,7 +297,7 @@ provides interactive mode (`-i` flag) which enables you to:
- **edit** the commit content (changes introduced by commit) and message. - **edit** the commit content (changes introduced by commit) and message.
- **squash** multiple commits into a single one, and have a custom or aggregated - **squash** multiple commits into a single one, and have a custom or aggregated
commit message. commit message.
- **drop** commits - simply delete them. - **drop** commits - delete them.
- and few more options. - and few more options.
Let us check few examples. Again there are commits `A-B-C-D` where you want to Let us check few examples. Again there are commits `A-B-C-D` where you want to
...@@ -326,8 +332,8 @@ In case you want to modify something introduced in commit `B`. ...@@ -326,8 +332,8 @@ In case you want to modify something introduced in commit `B`.
git commit -a git commit -a
``` ```
You can find some more examples in [below section where we explain how to modify You can find some more examples in the section explaining
history](#how-modifying-history-is-done) [how to modify history](#how-modifying-history-is-done).
### Redoing the Undo ### Redoing the Undo
...@@ -391,12 +397,12 @@ git checkout -b new-path-of-feature ...@@ -391,12 +397,12 @@ git checkout -b new-path-of-feature
## Undo remote changes with modifying history ## Undo remote changes with modifying history
This is useful when you want to *hide* certain things - like secret keys, This is useful when you want to *hide* certain things - like secret keys,
passwords, SSH keys, etc. It is and should not be used to hide mistakes, as passwords, and SSH keys. It is and should not be used to hide mistakes, as
it will make it harder to debug in case there are some other bugs. The main it makes it harder to debug in case there are some other bugs. The main
reason for this is that you loose the real development progress. **Also keep in reason for this is that you loose the real development progress. Keep in
mind that, even with modified history, commits are just detached and can still be mind that, even with modified history, commits are just detached and can still be
accessed through commit ID** - at least until all repositories perform accessed through commit ID - at least until all repositories perform
the cleanup of detached commits (happens automatically). the automated cleanup of detached commits.
![Modifying history causes problems on remote branch](img/rebase_reset.png) ![Modifying history causes problems on remote branch](img/rebase_reset.png)
...@@ -404,16 +410,16 @@ the cleanup of detached commits (happens automatically). ...@@ -404,16 +410,16 @@ the cleanup of detached commits (happens automatically).
Modified history breaks the development chain of other developers, as changed Modified history breaks the development chain of other developers, as changed
history does not have matching commit IDs. For that reason it should not be history does not have matching commit IDs. For that reason it should not be
used on any public branch or on branch that *might* be used by other developers. used on any public branch or on branch that might be used by other developers.
When contributing to big open source repositories (for example, [GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria) When contributing to big open source repositories (for example, [GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria)
itself), it is acceptable to *squash* commits into a single one, to present a itself), it is acceptable to squash commits into a single one, to present a
nicer history of your contribution. nicer history of your contribution.
Keep in mind that this also removes the comments attached to certain commits Keep in mind that this also removes the comments attached to certain commits
in merge requests, so if you need to retain traceability in GitLab, then in merge requests, so if you need to retain traceability in GitLab, then
modifying history is not acceptable. modifying history is not acceptable.
A feature-branch of a merge request is a public branch and might be used by A feature branch of a merge request is a public branch and might be used by
other developers, but project process and rules might allow or require other developers, but project process and rules might allow or require
you to use `git rebase` (command that changes history) to reduce number of you to use `git rebase` (command that changes history) to reduce number of
displayed commits on target branch after reviews are done (for example displayed commits on target branch after reviews are done (for example
...@@ -427,7 +433,7 @@ Never modify the commit history of `master` or shared branch. ...@@ -427,7 +433,7 @@ Never modify the commit history of `master` or shared branch.
### How modifying history is done ### How modifying history is done
After you know what you want to modify (how far in history or how which range of After you know what you want to modify (how far in history or how which range of
old commits), use `git rebase -i commit-id`. This command will then display all the commits from old commits), use `git rebase -i commit-id`. This command displays all the commits from
current version to chosen commit ID and allow modification, squashing, deletion current version to chosen commit ID and allow modification, squashing, deletion
of that commits. of that commits.
...@@ -458,12 +464,12 @@ pick <commit3-id> <commit3-commit-message> ...@@ -458,12 +464,12 @@ pick <commit3-id> <commit3-commit-message>
``` ```
NOTE: NOTE:
It is important to notice that comment from the output clearly states that, if The comment from the output clearly states that, if
you decide to abort, then do not just close your editor (as that will in-fact you decide to abort, don't just close your editor (as that
modify history), but remove all uncommented lines and save. modifies history), but remove all uncommented lines and save.
That is one of the reasons why `git rebase` should be used carefully on Use `git rebase` carefully on
shared and remote branches. But don't worry, there will be nothing broken until shared and remote branches, but rest assured: nothing is broken until
you push back to the remote repository (so you can freely explore the you push back to the remote repository (so you can freely explore the
different outcomes locally). different outcomes locally).
...@@ -486,7 +492,7 @@ file from history altogether use: ...@@ -486,7 +492,7 @@ file from history altogether use:
git filter-branch --tree-filter 'rm filename' HEAD git filter-branch --tree-filter 'rm filename' HEAD
``` ```
Since `git filter-branch` command might be slow on big repositories, there are Because `git filter-branch` command might be slow on big repositories, there are
tools that can use some of Git specifics to enable faster execution of common tools that can use some of Git specifics to enable faster execution of common
tasks (which is exactly what removing sensitive information file is about). tasks (which is exactly what removing sensitive information file is about).
An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/). An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/).
...@@ -497,8 +503,8 @@ Refer [Reduce repository size](../../../user/project/repository/reducing_the_rep ...@@ -497,8 +503,8 @@ Refer [Reduce repository size](../../../user/project/repository/reducing_the_rep
## Conclusion ## Conclusion
There are various options of undoing your work with any version control system, but Various options exist for undoing your work with any version control system, but
because of de-centralized nature of Git, these options are multiplied (or limited) because of the de-centralized nature of Git, these options are multiplied (or limited)
depending on the stage of your process. Git also enables rewriting history, but that depending on the stage of your process. Git also enables rewriting history, but that
should be avoided as it might cause problems when multiple developers are should be avoided as it might cause problems when multiple developers are
contributing to the same codebase. contributing to the same codebase.
......
doc/topics/git/useful_git_commands.md
View file @ 15b9bc05
...@@ -7,8 +7,8 @@ type: reference ...@@ -7,8 +7,8 @@ type: reference
# Useful Git commands # Useful Git commands
Here are some useful Git commands collected by the GitLab support team. You may not The GitLab support team has collected these commands to help you. You may not
need to use often, but they can come in handy when needed. need to use them often.
## Remotes ## Remotes
...@@ -182,7 +182,7 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s ...@@ -182,7 +182,7 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s
### Rebase your branch onto master ### Rebase your branch onto master
The -i flag stands for 'interactive': The `-i` flag stands for 'interactive':
```shell ```shell
git rebase -i master git rebase -i master
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7