diff options
Diffstat (limited to 'doc/user/workflow')
147 files changed, 1915 insertions, 0 deletions
diff --git a/doc/user/workflow/README.md b/doc/user/workflow/README.md new file mode 100644 index 00000000000..9efe41308dc --- /dev/null +++ b/doc/user/workflow/README.md @@ -0,0 +1,28 @@ +# Workflow + +- [Authorization for merge requests](authorization_for_merge_requests.md) +- [Change your time zone](timezone.md) +- [Feature branch workflow](workflow.md) +- [GitLab Flow](gitlab_flow.md) +- [Groups](groups.md) +- [Keyboard shortcuts](shortcuts.md) +- [File finder](file_finder.md) +- [Labels](labels.md) +- [Notification emails](notifications.md) +- [Project Features](project_features.md) +- [Project forking workflow](forking_workflow.md) +- [Project users](add-user/add-user.md) +- [Protected branches](protected_branches.md) +- [Sharing a project with a group](share_with_group.md) +- [Share projects with other groups](share_projects_with_other_groups.md) +- [Web Editor](web_editor.md) +- [Releases](releases.md) +- [Milestones](milestones.md) +- [Merge Requests](merge_requests.md) +- [Revert changes](revert_changes.md) +- [Cherry-pick changes](cherry_pick_changes.md) +- ["Work In Progress" Merge Requests](wip_merge_requests.md) +- [Merge When Build Succeeds](merge_when_build_succeeds.md) +- [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md) +- [Importing from SVN, GitHub, BitBucket, etc](importing/README.md) +- [Todos](todos.md) diff --git a/doc/user/workflow/add-user/add-user.md b/doc/user/workflow/add-user/add-user.md new file mode 100644 index 00000000000..4b551130255 --- /dev/null +++ b/doc/user/workflow/add-user/add-user.md @@ -0,0 +1,111 @@ +# Project users + +You can manage the groups and users and their access levels in all of your +projects. You can also personalize the access level you give each user, +per-project. + +You should have `master` or `owner` permissions to add or import a new user +to your project. + +The first step to add or import a user, go to your project and click on +**Members** in the drop-down menu on the right side of your screen. + + + +--- + +## Add a user + +Right next to **People**, start typing the name or username of the user you +want to add. + + + +--- + +Select the user and the [permission level](../../permissions/permissions.md) +that you'd like to give the user. Note that you can select more than one user. + + + +--- + +Once done, hit **Add users to project** and they will be immediately added to +your project with the permissions you gave them above. + + + +--- + +From there on, you can either remove an existing user or change their access +level to the project. + +## Import users from another project + +You can import another project's users in your own project by hitting the +**Import members** button on the upper right corner of the **Members** menu. + +In the dropdown menu, you can see only the projects you are Master on. + + + +--- + +Select the one you want and hit **Import project members**. A flash message +notifying you that the import was successful will appear, and the new members +are now in the project's members list. Notice that the permissions that they +had on the project you imported from are retained. + + + +--- + +## Invite people using their e-mail address + +If a user you want to give access to doesn't have an account on your GitLab +instance, you can invite them just by typing their e-mail address in the +user search field. + + + +--- + +As you can imagine, you can mix inviting multiple people and adding existing +GitLab users to the project. + + + +--- + +Once done, hit **Add users to project** and watch that there is a new member +with the e-mail address we used above. From there on, you can resend the +invitation, change their access level or even delete them. + + + +--- + +Once the user accepts the invitation, they will be prompted to create a new +GitLab account using the same e-mail address the invitation was sent to. + +## Request access to a project + +As a user, you can request to be a member of a project. Go to the project you'd +like to be a member of, and click the **Request Access** button on the right +side of your screen. + + + +--- + +Project owners & masters will be notified of your request and will be able to approve or +decline it on the members page. + + + +--- + +If you change your mind before your request is approved, just click the +**Withdraw Access Request** button. + + diff --git a/doc/user/workflow/add-user/img/access_requests_management.png b/doc/user/workflow/add-user/img/access_requests_management.png Binary files differnew file mode 100644 index 00000000000..e9641cb4f85 --- /dev/null +++ b/doc/user/workflow/add-user/img/access_requests_management.png diff --git a/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png b/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png Binary files differnew file mode 100644 index 00000000000..3da18cdae53 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png diff --git a/doc/user/workflow/add-user/img/add_user_email_accept.png b/doc/user/workflow/add-user/img/add_user_email_accept.png Binary files differnew file mode 100644 index 00000000000..18aabf93d50 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_email_accept.png diff --git a/doc/user/workflow/add-user/img/add_user_email_ready.png b/doc/user/workflow/add-user/img/add_user_email_ready.png Binary files differnew file mode 100644 index 00000000000..385d64330c0 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_email_ready.png diff --git a/doc/user/workflow/add-user/img/add_user_email_search.png b/doc/user/workflow/add-user/img/add_user_email_search.png Binary files differnew file mode 100644 index 00000000000..84741edbca4 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_email_search.png diff --git a/doc/user/workflow/add-user/img/add_user_give_permissions.png b/doc/user/workflow/add-user/img/add_user_give_permissions.png Binary files differnew file mode 100644 index 00000000000..7e580384e54 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_give_permissions.png diff --git a/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png b/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png Binary files differnew file mode 100644 index 00000000000..8dbd73a5bc8 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png diff --git a/doc/user/workflow/add-user/img/add_user_imported_members.png b/doc/user/workflow/add-user/img/add_user_imported_members.png Binary files differnew file mode 100644 index 00000000000..abac1f59c02 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_imported_members.png diff --git a/doc/user/workflow/add-user/img/add_user_list_members.png b/doc/user/workflow/add-user/img/add_user_list_members.png Binary files differnew file mode 100644 index 00000000000..e17d88c6f5f --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_list_members.png diff --git a/doc/user/workflow/add-user/img/add_user_members_menu.png b/doc/user/workflow/add-user/img/add_user_members_menu.png Binary files differnew file mode 100644 index 00000000000..ec5d39f402d --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_members_menu.png diff --git a/doc/user/workflow/add-user/img/add_user_search_people.png b/doc/user/workflow/add-user/img/add_user_search_people.png Binary files differnew file mode 100644 index 00000000000..eaa062376f4 --- /dev/null +++ b/doc/user/workflow/add-user/img/add_user_search_people.png diff --git a/doc/user/workflow/add-user/img/request_access_button.png b/doc/user/workflow/add-user/img/request_access_button.png Binary files differnew file mode 100644 index 00000000000..984d640b0f0 --- /dev/null +++ b/doc/user/workflow/add-user/img/request_access_button.png diff --git a/doc/user/workflow/add-user/img/withdraw_access_request_button.png b/doc/user/workflow/add-user/img/withdraw_access_request_button.png Binary files differnew file mode 100644 index 00000000000..ff54a0e4384 --- /dev/null +++ b/doc/user/workflow/add-user/img/withdraw_access_request_button.png diff --git a/doc/user/workflow/authorization_for_merge_requests.md b/doc/user/workflow/authorization_for_merge_requests.md new file mode 100644 index 00000000000..d1d6d94ec11 --- /dev/null +++ b/doc/user/workflow/authorization_for_merge_requests.md @@ -0,0 +1,40 @@ +# Authorization for Merge requests + +There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project. + +## Protected branch flow + +With the protected branch flow everybody works within the same GitLab project. + +The project maintainers get Master access and the regular developers get Developer access. + +The maintainers mark the authoritative branches as 'Protected'. + +The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. + +Only users with Master access can merge changes into a protected branch. + +### Advantages + +- fewer projects means less clutter +- developers need to consider only one remote repository + +### Disadvantages + +- manual setup of protected branch required for each new project + +## Forking workflow + +With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. + +Developers create forks of the authoritative project and push their feature branches to their own forks. + +To get their changes into master they need to create a merge request across forks. + +### Advantages + +- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects + +### Disadvantages + +- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes) diff --git a/doc/user/workflow/award_emoji.md b/doc/user/workflow/award_emoji.md new file mode 100644 index 00000000000..70b35c58be6 --- /dev/null +++ b/doc/user/workflow/award_emoji.md @@ -0,0 +1,48 @@ +# Award emojis + +>**Note:** +This feature was [introduced][1825] in GitLab 8.2. + +When you're collaborating online, you get fewer opportunities for high-fives +and thumbs-ups. In order to make virtual celebrations easier, you can now vote +on issues and merge requests using emoji! + + + +This makes it much easier to give and receive feedback, without a long comment +thread. Any comment that contains only the thumbs up or down emojis is +converted to a vote and depicted in the emoji area. + +You can then use that functionality to sort issues and merge requests based on +popularity. + +## Sort issues and merge requests on vote count + +>**Note:** +This feature was [introduced][2871] in GitLab 8.5. + +You can quickly sort the issues or merge requests by the number of votes they +have received. The sort option can be found in the right dropdown menu. + + + +--- + +Sort by most popular issues/merge requests. + + + +--- + +Sort by least popular issues/merge requests. + + + +--- + +The number of upvotes and downvotes is not summed up. That means that an issue +with 18 upvotes and 5 downvotes is considered more popular than an issue with +17 upvotes and no downvotes. + +[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781 +[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825 diff --git a/doc/user/workflow/award_emoji.png b/doc/user/workflow/award_emoji.png Binary files differnew file mode 100644 index 00000000000..fb26ee04393 --- /dev/null +++ b/doc/user/workflow/award_emoji.png diff --git a/doc/user/workflow/cherry_pick_changes.md b/doc/user/workflow/cherry_pick_changes.md new file mode 100644 index 00000000000..4a499009842 --- /dev/null +++ b/doc/user/workflow/cherry_pick_changes.md @@ -0,0 +1,53 @@ +# Cherry-pick changes + +>**Note:** +This feature was [introduced][ce-3514] in GitLab 8.7. + +--- + +GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick] +with introducing a **Cherry-pick** button in Merge Requests and commit details. + +## Cherry-picking a Merge Request + +After the Merge Request has been merged, a **Cherry-pick** button will be available +to cherry-pick the changes introduced by that Merge Request: + + + +--- + +You can cherry-pick the changes directly into the selected branch or you can opt to +create a new Merge Request with the cherry-pick changes: + + + +## Cherry-picking a Commit + +You can cherry-pick a Commit from the Commit details page: + + + +--- + +Similar to cherry-picking a Merge Request, you can opt to cherry-pick the changes +directly into the target branch or create a new Merge Request to cherry-pick the +changes: + + + +--- + +Please note that when cherry-picking merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line. + +Here is a quick example to cherry-pick a merge commit using the second parent as the +mainline: + +```bash +git cherry-pick -m 2 7a39eb0 +``` + +[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request" +[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation" diff --git a/doc/user/workflow/ci_mr.png b/doc/user/workflow/ci_mr.png Binary files differnew file mode 100644 index 00000000000..a577356f8e8 --- /dev/null +++ b/doc/user/workflow/ci_mr.png diff --git a/doc/user/workflow/close_issue_mr.png b/doc/user/workflow/close_issue_mr.png Binary files differnew file mode 100644 index 00000000000..a136d642e12 --- /dev/null +++ b/doc/user/workflow/close_issue_mr.png diff --git a/doc/user/workflow/environment_branches.png b/doc/user/workflow/environment_branches.png Binary files differnew file mode 100644 index 00000000000..ee893ced13b --- /dev/null +++ b/doc/user/workflow/environment_branches.png diff --git a/doc/user/workflow/file_finder.md b/doc/user/workflow/file_finder.md new file mode 100644 index 00000000000..b69ae663272 --- /dev/null +++ b/doc/user/workflow/file_finder.md @@ -0,0 +1,46 @@ +# File finder + +_**Note:** This feature was [introduced][gh-9889] in GitLab 8.4._ + +--- + +The file finder feature allows you to quickly shortcut your way when you are +searching for a file in a repository using the GitLab UI. + +You can find the **Find File** button when in the **Files** section of a +project. + + + +--- + +For those who prefer to keep their fingers on the keyboard, there is a +[shortcut button](shortcuts.md) as well, which you can invoke from _anywhere_ +in a project. + +Press `t` to launch the File search function when in **Issues**, +**Merge requests**, **Milestones**, even the project's settings. + +Start typing what you are searching for and watch the magic happen. With the +up/down arrows, you go up and down the results, with `Esc` you close the search +and go back to **Files**. + +## How it works + +The File finder feature is powered by the [Fuzzy filter] library. + +It implements a fuzzy search with highlight, and tries to provide intuitive +results by recognizing patterns that people use while searching. + +For example, consider the [GitLab CE repository][ce] and that we want to open +the `app/controllers/admin/deploy_keys_controller.rb` file. + +Using fuzzy search, we start by typing letters that get us closer to the file. + +**Protip:** To narrow down your search, include `/` in your search terms. + + + +[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request" +[fuzzy filter]: https://github.com/jeancroy/fuzzaldrin-plus "fuzzaldrin-plus on GitHub" +[ce]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master "GitLab CE repository" diff --git a/doc/user/workflow/forking/branch_select.png b/doc/user/workflow/forking/branch_select.png Binary files differnew file mode 100644 index 00000000000..275f64d113b --- /dev/null +++ b/doc/user/workflow/forking/branch_select.png diff --git a/doc/user/workflow/forking/merge_request.png b/doc/user/workflow/forking/merge_request.png Binary files differnew file mode 100644 index 00000000000..2dc00ed08a1 --- /dev/null +++ b/doc/user/workflow/forking/merge_request.png diff --git a/doc/user/workflow/forking_workflow.md b/doc/user/workflow/forking_workflow.md new file mode 100644 index 00000000000..217a4a4012f --- /dev/null +++ b/doc/user/workflow/forking_workflow.md @@ -0,0 +1,59 @@ +# Project forking workflow + +Forking a project to your own namespace is useful if you have no write +access to the project you want to contribute to. If you do have write +access or can request it, we recommend working together in the same +repository since it is simpler. See our [GitLab Flow](gitlab_flow.md) +document more information about using branches to work together. + +## Creating a fork + +Forking a project is in most cases a two-step process. + + +1. Click on the fork button located in the middle of the page or a project's + home page right next to the stars button. + +  + + --- + +1. Once you do that, you'll be presented with a screen where you can choose + the namespace to fork to. Only namespaces (groups and your own + namespace) where you have write access to, will be shown. Click on the + namespace to create your fork there. + +  + + --- + + **Note:** + If the namespace you chose to fork the project to has another project with + the same path name, you will be presented with a warning that the forking + could not be completed. Try to resolve the error and repeat the forking + process. + +  + + --- + +After the forking is done, you can start working on the newly created +repository. There, you will have full [Owner](../permissions/permissions.md) +access, so you can set it up as you please. + +## Merging upstream + +Once you are ready to send your code back to the main project, you need +to create a merge request. Choose your forked project's main branch as +the source and the original project's main branch as the destination and +create the [merge request](merge_requests.md). + + + +You can then assign the merge request to someone to have them review +your changes. Upon pressing the 'Accept Merge Request' button, your +changes will be added to the repository and branch you're merging into. + + + +[gitlab flow]: https://about.gitlab.com/2014/09/29/gitlab-flow/ "GitLab Flow blog post" diff --git a/doc/user/workflow/four_stages.png b/doc/user/workflow/four_stages.png Binary files differnew file mode 100644 index 00000000000..2f444fc6f79 --- /dev/null +++ b/doc/user/workflow/four_stages.png diff --git a/doc/user/workflow/git_pull.png b/doc/user/workflow/git_pull.png Binary files differnew file mode 100644 index 00000000000..7d47064eb14 --- /dev/null +++ b/doc/user/workflow/git_pull.png diff --git a/doc/user/workflow/gitdashflow.png b/doc/user/workflow/gitdashflow.png Binary files differnew file mode 100644 index 00000000000..f2f091dd10b --- /dev/null +++ b/doc/user/workflow/gitdashflow.png diff --git a/doc/user/workflow/github_flow.png b/doc/user/workflow/github_flow.png Binary files differnew file mode 100644 index 00000000000..88addb623ee --- /dev/null +++ b/doc/user/workflow/github_flow.png diff --git a/doc/user/workflow/gitlab_flow.md b/doc/user/workflow/gitlab_flow.md new file mode 100644 index 00000000000..2b2f140f8bf --- /dev/null +++ b/doc/user/workflow/gitlab_flow.md @@ -0,0 +1,317 @@ + + +## Introduction + +Version management with git makes branching and merging much easier than older versioning systems such as SVN. +This allows a wide variety of branching strategies and workflows. +Almost all of these are an improvement over the methods used before git. +But many organizations end up with a workflow that is not clearly defined, overly complex or not integrated with issue tracking systems. +Therefore we propose the GitLab flow as clearly defined set of best practices. +It combines [feature driven development](https://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](http://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. + +Organizations coming to git from other version control systems frequently find it hard to develop an effective workflow. +This article describes the GitLab flow that integrates the git workflow with an issue tracking system. +It offers a simple, transparent and effective way to work with git. + + + +When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues. +Most version control systems have only one step, committing from the working copy to a shared server. +In git you add files from the working copy to the staging area. After that you commit them to the local repo. +The third step is pushing to a shared remote repository. +After getting used to these three steps the branching model becomes the challenge. + + + +Since many organizations new to git have no conventions how to work with it, it can quickly become a mess. +The biggest problem they run into is that many long running branches that each contain part of the changes are around. +People have a hard time figuring out which branch they should develop on or deploy to production. +Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). +We think there is still room for improvement and will detail a set of practices we call GitLab flow. + +## Git flow and its problems + + + +Git flow was one of the first proposals to use git branches and it has gotten a lot of attention. +It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes. +The development happens on the develop branch, moves to a release branch and is finally merged into the master branch. +Git flow is a well defined standard but its complexity introduces two problems. +The first problem is that developers must use the develop branch and not master, master is reserved for code that is released to production. +It is a convention to call your default branch master and to mostly branch from and merge to this. +Since most tools automatically make the master branch the default one and display that one by default it is annoying to have to switch to another one. +The second problem of git flow is the complexity introduced by the hotfix and release branches. +These branches can be a good idea for some organizations but are overkill for the vast majority of them. +Nowadays most organizations practice continuous delivery which means that your default branch can be deployed. +This means that hotfix and release branches can be prevented including all the ceremony they introduce. +An example of this ceremony is the merging back of release branches. +Though specialized tools do exist to solve this, they require documentation and add complexity. +Frequently developers make a mistake and for example changes are only merged into master and not into the develop branch. +The root cause of these errors is that git flow is too complex for most of the use cases. +And doing releases doesn't automatically mean also doing hotfixes. + +## GitHub flow as a simpler alternative + + + +In reaction to git flow a simpler alternative was detailed, [GitHub flow](https://guides.github.com/introduction/flow/index.html). +This flow has only feature branches and a master branch. +This is very simple and clean, many organizations have adopted it with great success. +Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches. +Merging everything into the master branch and deploying often means you minimize the amount of code in 'inventory' which is in line with the lean and continuous delivery best practices. +But this flow still leaves a lot of questions unanswered regarding deployments, environments, releases and integrations with issues. +With GitLab flow we offer additional guidance for these questions. + +## Production branch with GitLab flow + + + +GitHub flow does assume you are able to deploy to production every time you merge a feature branch. +This is possible for SaaS applications but are many cases where this is not possible. +One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass App Store validation. +Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times. +In these cases you can make a production branch that reflects the deployed code. +You can deploy a new version by merging in master to the production branch. +If you need to know what code is in production you can just checkout the production branch to see. +The approximate time of deployment is easily visible as the merge commit in the version control system. +This time is pretty accurate if you automatically deploy your production branch. +If you need a more exact time you can have your deployment script create a tag on each deployment. +This flow prevents the overhead of releasing, tagging and merging that is common to git flow. + +## Environment branches with GitLab flow + + + +It might be a good idea to have an environment that is automatically updated to the master branch. +Only in this case, the name of this environment might differ from the branch name. +Suppose you have a staging environment, a pre-production environment and a production environment. +In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch. +And going live with code happens by merging the pre-production branch into the production branch. +This workflow where commits only flow downstream ensures that everything has been tested on all environments. +If you need to cherry-pick a commit with a hotfix it is common to develop it on a feature branch and merge it into master with a merge request, do not delete the feature branch. +If master is good to go (it should be if you a practicing [continuous delivery](http://martinfowler.com/bliki/ContinuousDelivery.html)) you then merge it to the other branches. +If this is not possible because more manual testing is required you can send merge requests from the feature branch to the downstream branches. +An 'extreme' version of environment branches are setting up an environment for each feature branch as done by [Teatro](https://teatro.io/). + +## Release branches with GitLab flow + + + +Only in case you need to release software to the outside world you need to work with release branches. +In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.). +The stable branch uses master as a starting point and is created as late as possible. +By branching as late as possible you minimize the time you have to apply bug fixes to multiple branches. +After a release branch is announced, only serious bug fixes are included in the release branch. +If possible these bug fixes are first merged into master and then cherry-picked into the release branch. +This way you can't forget to cherry-pick them into master and encounter the same bug on subsequent releases. +This is called an 'upstream first' policy that is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/about/news/archive/2013/5/a-community-for-using-openstack-with-red-hat-rdo). +Every time a bug-fix is included in a release branch the patch version is raised (to comply with [Semantic Versioning](http://semver.org/)) by setting a new tag. +Some projects also have a stable branch that points to the same commit as the latest released branch. +In this flow it is not common to have a production branch (or git flow master branch). + +## Merge/pull requests with GitLab flow + + + +Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. +Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch. +Tools such as GitLab and Gitorious choose the name merge request since that is the final action that is requested of the assignee. +In this article we'll refer to them as merge requests. + +If you work on a feature branch for more than a few hours it is good to share the intermediate result with the rest of the team. +This can be done by creating a merge request without assigning it to anyone, instead you mention people in the description or a comment (/cc @mark @susan). +This means it is not ready to be merged but feedback is welcome. +Your team members can comment on the merge request in general or on specific lines with line comments. +The merge requests serves as a code review tool and no separate tools such as Gerrit and reviewboard should be needed. +If the review reveals shortcomings anyone can commit and push a fix. +Commonly the person to do this is the creator of the merge/pull request. +The diff in the merge/pull requests automatically updates when new commits are pushed on the branch. + +When you feel comfortable with it to be merged you assign it to the person that knows most about the codebase you are changing and mention any other people you would like feedback from. +There is room for more feedback and after the assigned person feels comfortable with the result the branch is merged. +If the assigned person does not feel comfortable they can close the merge request without merging. + +In GitLab it is common to protect the long-lived branches (e.g. the master branch) so that normal developers [can't modify these protected branches](http://docs.gitlab.com/ce/permissions/permissions.html). +So if you want to merge it into a protected branch you assign it to someone with master authorizations. + +## Issues with GitLab flow + + + +GitLab flow is a way to make the relation between the code and the issue tracker more transparent. + +Any significant change to the code should start with an issue where the goal is described. +Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small. +In GitLab each change to the codebase starts with an issue in the issue tracking system. +If there is no issue yet it should be created first provided there is significant work involved (more than 1 hour). +For many organizations this will be natural since the issue will have to be estimated for the sprint. +Issue titles should describe the desired state of the system, e.g. "As an administrator I want to remove users without receiving an error" instead of "Admin can't remove users.". + +When you are ready to code you start a branch for the issue from the master branch. +The name of this branch should start with the issue number, for example '15-require-a-password-to-change-it'. + +When you are done or want to discuss the code you open a merge request. +This is an online place to discuss the change and review the code. +Opening a merge request is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch. +If you open the merge request but do not assign it to anyone it is a 'Work In Progress' merge request. +These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet. +_Pro tip:_ Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready. + +When the author thinks the code is ready the merge request is assigned to reviewer. +The reviewer presses the merge button when they think the code is ready for inclusion in the master branch. +In this case the code is merged and a merge commit is generated that makes this event easily visible later on. +Merge requests always create a merge commit even when the commit could be added without one. +This merge strategy is called 'no fast-forward' in git. +After the merge the feature branch is deleted since it is no longer needed, in GitLab this deletion is an option when merging. + +Suppose that a branch is merged but a problem occurs and the issue is reopened. +In this case it is no problem to reuse the same branch name since it was deleted when the branch was merged. +At any time there is at most one branch for every issue. +It is possible that one feature branch solves more than one issue. + +## Linking and closing issues from merge requests + + + +Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description. +In GitLab this creates a comment in the issue that the merge requests mentions the issue. +And the merge request shows the linked issues. +These issues are closed once code is merged into the default branch. + +If you only want to make the reference without closing the issue you can also just mention it: "Duck typing is preferred. #12". + +If you have an issue that spans across multiple repositories, the best thing is to create an issue for each repository and link all issues to a parent issue. + +## Squashing commits with rebase + + + +With git you can use an interactive rebase (`rebase -i`) to squash multiple commits into one and reorder them. +In GitLab EE and .com you can also [rebase before merge](http://docs.gitlab.com/ee/workflow/rebase_before_merge.html) from the web interface. +This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. +However you should never rebase commits you have pushed to a remote server. +Somebody can have referred to the commits or cherry-picked them. +When you rebase you change the identifier (SHA-1) of the commit and this is confusing. +If you do that the same change will be known under multiple identifiers and this can cause much confusion. +If people already reviewed your code it will be hard for them to review only the improvements you made since then if you have rebased everything into one commit. +Another reasons not to rebase is that you lose authorship information, maybe someone created a merge request, another person pushed a commit on there to improve it and a third one merged it. +In this case rebasing all the commits into one prevent the other authors from being properly attributed and sharing part of the [git blame](https://git-scm.com/docs/git-blame). + +People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on. +This will lead to many commits per change which makes the history harder to understand. +But the advantages of having stable identifiers outweigh this drawback. +And to understand a change in context one can always look at the merge commit that groups all the commits together when the code is merged into the master branch. + +After you merge multiple commits from a feature branch into the master branch this is harder to undo. +If you would have squashed all the commits into one you could have just reverted this commit but as we indicated you should not rebase commits after they are pushed. +Fortunately [reverting a merge made some time ago](https://git-scm.com/blog/2010/03/02/undoing-merges.html) can be done with git. +This however, requires having specific merge commits for the commits your want to revert. +If you revert a merge and you change your mind, revert the revert instead of merging again since git will not allow you to merge the code again otherwise. + +Being able to revert a merge is a good reason always to create a merge commit when you merge manually with the `--no-ff` option. +Git management software will always create a merge commit when you accept a merge request. + +## Do not order commits with rebase + + + +With git you can also rebase your feature branch commits to order them after the commits on the master branch. +This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history. +However, just like with squashing you should never rebase commits you have pushed to a remote server. +This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend. +When using rebase to keep your feature branch updated you [need to resolve similar conflicts again and again](https://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/). +You can reuse recorded resolutions (rerere) sometimes, but without rebasing you only have to solve the conflicts one time and you’re set. +There has to be a better way to avoid many merge commits. + +The way to prevent creating many merge commits is to not frequently merge master into the feature branch. +We'll discuss the three reasons to merge in master: leveraging code, merge conflicts, and long running branches. +If you need to leverage some code that was introduced in master after you created the feature branch you can sometimes solve this by just cherry-picking a commit. +If your feature branch has a merge conflict, creating a merge commit is a normal way of solving this. +You can prevent some merge conflicts by using [gitattributes](http://git-scm.com/docs/gitattributes) for files that can be in a random order. +For example in GitLab our changelog file is specified in .gitattributes as `CHANGELOG merge=union` so that there are fewer merge conflicts in it. +The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project. +Martin Fowler, in [his article about feature branches](http://martinfowler.com/bliki/FeatureBranch.html) talks about this Continuous Integration (CI). +At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. +That's continuous building, and a Good Thing, but there's no integration, so it's not CI.". +The solution to prevent many merge commits is to keep your feature branches short-lived, the vast majority should take less than one day of work. +If your feature branches commonly take more than a day of work, look into ways to create smaller units of work and/or use [feature toggles](http://martinfowler.com/bliki/FeatureToggle.html). +As for the long running branches that take more than one day there are two strategies. +In a CI strategy you can merge in master at the start of the day to prevent painful merges at a later time. +In a synchronization point strategy you only merge in from well defined points in time, for example a tagged release. +This strategy is [advocated by Linus Torvalds](https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html) because the state of the code at these points is better known. + +In conclusion, we can say that you should try to prevent merge commits, but not eliminate them. +Your codebase should be clean but your history should represent what actually happened. +Developing software happen in small messy steps and it is OK to have your history reflect this. +You can use tools to view the network graphs of commits and understand the messy history that created your code. +If you rebase code the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers. + +## Award emojis on issues and merge requests + + + +It is common to voice approval or disapproval by using +1 or -1. In GitLab you +can use emojis to give a virtual high five on issues and merge requests. + +## Pushing and removing branches + + + +We recommend that people push their feature branches frequently, even when they are not ready for review yet. +By doing this you prevent team members from accidentally starting to work on the same issue. +Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software. +However sometimes one of the two parties forgets to assign someone in the issue tracking software. +After a branch is merged it should be removed from the source control software. +In GitLab and similar systems this is an option when merging. +This ensures that the branch overview in the repository management software shows only work in progress. +This also ensures that when someone reopens the issue a new branch with the same name can be used without problem. +When you reopen an issue you need to create a new merge request. + +## Committing often and with the right message + + + +We recommend to commit early and often. +Each time you have a functioning set of tests and code a commit can be made. +The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version. +This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. +The trick is to use the merge/pull request with multiple commits when your work is ready to share. +The commit message should reflect your intention, not the contents of the commit. +The contents of the commit can be easily seen anyway, the question is why you did it. +An example of a good commit message is: "Combine templates to dry up the user views.". +Some words that are bad commit messages because they don't contain munch information are: change, improve and refactor. +The word fix or fixes is also a red flag, unless it comes after the commit sentence and references an issue number. +To see more information about the formatting of commit messages please see this great [blog post by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +## Testing before merging + + + +In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. +Developers had to ensure their code did not break the master branch. +When using GitLab flow developers create their branches from this master branch so it is essential it is green. +Therefore each merge request must be tested before it is accepted. +CI software like Travis and GitLab CI show the build results right in the merge request itself to make this easy. +One drawback is that they are testing the feature branch itself and not the merged result. +What one can do to improve this is to test the merged result itself. +The problem is that the merge result changes every time something is merged into master. +Retesting on every commit to master is computationally expensive and means you are more frequently waiting for test results. +If there are no merge conflicts and the feature branches are short lived the risk is acceptable. +If there are merge conflicts you merge the master branch into the feature branch and the CI server will rerun the tests. +If you have long lived feature branches that last for more than a few days you should make your issues smaller. + +## Merging in other code + + + +When initiating a feature branch, always start with an up to date master to branch off from. +If you know beforehand that your work absolutely depends on another branch you can also branch from there. +If you need to merge in another branch after starting explain the reason in the merge commit. +If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch. +Do not merge in upstream if your code will work and merge cleanly without doing so, Linus even says that [you should never merge in upstream at random points, only at major releases](https://lwn.net/Articles/328438/). +Merging only when needed prevents creating merge commits in your feature branch that later end up littering the master history. + +### References + +- [Sketch file](https://www.dropbox.com/s/58dvsj5votbwrzv/git_flows.sketch?dl=0) with vectors of images in this article +- [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/) diff --git a/doc/user/workflow/gitlab_flow.png b/doc/user/workflow/gitlab_flow.png Binary files differnew file mode 100644 index 00000000000..1ea191a672b --- /dev/null +++ b/doc/user/workflow/gitlab_flow.png diff --git a/doc/user/workflow/good_commit.png b/doc/user/workflow/good_commit.png Binary files differnew file mode 100644 index 00000000000..3737a026644 --- /dev/null +++ b/doc/user/workflow/good_commit.png diff --git a/doc/user/workflow/groups.md b/doc/user/workflow/groups.md new file mode 100644 index 00000000000..1a316e80976 --- /dev/null +++ b/doc/user/workflow/groups.md @@ -0,0 +1,93 @@ +# GitLab Groups + +GitLab groups allow you to group projects into directories and give users to several projects at once. + +When you create a new project in GitLab, the default namespace for the project is the personal namespace associated with your GitLab user. +In this document we will see how to create groups, put projects in groups and manage who can access the projects in a group. + +## Creating groups + +You can create a group by going to the 'Groups' tab of the GitLab dashboard and clicking the 'New group' button. + + + +Next, enter the name (required) and the optional description and group avatar. + + + +When your group has been created you are presented with the group dashboard feed, which will be empty. + + + +You can use the 'New project' button to add a project to the new group. + +## Transferring an existing project into a group + +You can transfer an existing project into a group you own from the project settings page. +First scroll down to the 'Dangerous settings' and click 'Show them to me'. +Now you can pick any of the groups you manage as the new namespace for the group. + + + +GitLab administrators can use the admin interface to move any project to any namespace if needed. + +## Adding users to a group + +One of the benefits of putting multiple projects in one group is that you can give a user to access to all projects in the group with one action. + +Suppose we have a group with two projects. + + + +On the 'Group Members' page we can now add a new user Barry to the group. + + + +Now because Barry is a 'Developer' member of the 'Open Source' group, he automatically gets 'Developer' access to all projects in the 'Open Source' group. + + + +If necessary, you can increase the access level of an individual user for a specific project, by adding them as a Member to the project. + + + +## Request access to a group + +As a user, you can request to be a member of a group. Go to the group you'd +like to be a member of, and click the **Request Access** button on the right +side of your screen. + + + +--- + +Group owners & masters will be notified of your request and will be able to approve or +decline it on the members page. + + + +--- + +If you change your mind before your request is approved, just click the +**Withdraw Access Request** button. + + + +## Managing group memberships via LDAP + +In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. +See [the GitLab Enterprise Edition documentation](http://docs.gitlab.com/ee/integration/ldap.html) for more information. + +## Allowing only admins to create groups + +By default, any GitLab user can create new groups. +This ability can be disabled for individual users from the admin panel. +It is also possible to configure GitLab so that new users default to not being able to create groups: + +``` +# For omnibus-gitlab, put the following in /etc/gitlab/gitlab.rb +gitlab_rails['gitlab_default_can_create_group'] = false + +# For installations from source, uncomment the 'default_can_create_group' +# line in /home/git/gitlab/config/gitlab.yml +``` diff --git a/doc/user/workflow/groups/access_requests_management.png b/doc/user/workflow/groups/access_requests_management.png Binary files differnew file mode 100644 index 00000000000..ffede8e9bd6 --- /dev/null +++ b/doc/user/workflow/groups/access_requests_management.png diff --git a/doc/user/workflow/groups/add_member_to_group.png b/doc/user/workflow/groups/add_member_to_group.png Binary files differnew file mode 100644 index 00000000000..fa340ce572f --- /dev/null +++ b/doc/user/workflow/groups/add_member_to_group.png diff --git a/doc/user/workflow/groups/group_dashboard.png b/doc/user/workflow/groups/group_dashboard.png Binary files differnew file mode 100644 index 00000000000..7fc9048d74d --- /dev/null +++ b/doc/user/workflow/groups/group_dashboard.png diff --git a/doc/user/workflow/groups/group_with_two_projects.png b/doc/user/workflow/groups/group_with_two_projects.png Binary files differnew file mode 100644 index 00000000000..87242781e4f --- /dev/null +++ b/doc/user/workflow/groups/group_with_two_projects.png diff --git a/doc/user/workflow/groups/max_access_level.png b/doc/user/workflow/groups/max_access_level.png Binary files differnew file mode 100644 index 00000000000..71106a8a5a0 --- /dev/null +++ b/doc/user/workflow/groups/max_access_level.png diff --git a/doc/user/workflow/groups/new_group_button.png b/doc/user/workflow/groups/new_group_button.png Binary files differnew file mode 100644 index 00000000000..51e82798658 --- /dev/null +++ b/doc/user/workflow/groups/new_group_button.png diff --git a/doc/user/workflow/groups/new_group_form.png b/doc/user/workflow/groups/new_group_form.png Binary files differnew file mode 100644 index 00000000000..bf992c40bc2 --- /dev/null +++ b/doc/user/workflow/groups/new_group_form.png diff --git a/doc/user/workflow/groups/other_group_sees_shared_project.png b/doc/user/workflow/groups/other_group_sees_shared_project.png Binary files differnew file mode 100644 index 00000000000..cbf2c3c1fdc --- /dev/null +++ b/doc/user/workflow/groups/other_group_sees_shared_project.png diff --git a/doc/user/workflow/groups/override_access_level.png b/doc/user/workflow/groups/override_access_level.png Binary files differnew file mode 100644 index 00000000000..f4225a63679 --- /dev/null +++ b/doc/user/workflow/groups/override_access_level.png diff --git a/doc/user/workflow/groups/project_members_via_group.png b/doc/user/workflow/groups/project_members_via_group.png Binary files differnew file mode 100644 index 00000000000..b13cb1cfd95 --- /dev/null +++ b/doc/user/workflow/groups/project_members_via_group.png diff --git a/doc/user/workflow/groups/request_access_button.png b/doc/user/workflow/groups/request_access_button.png Binary files differnew file mode 100644 index 00000000000..ff0ac8747a7 --- /dev/null +++ b/doc/user/workflow/groups/request_access_button.png diff --git a/doc/user/workflow/groups/share_project_with_groups.png b/doc/user/workflow/groups/share_project_with_groups.png Binary files differnew file mode 100644 index 00000000000..a5dbc89fe90 --- /dev/null +++ b/doc/user/workflow/groups/share_project_with_groups.png diff --git a/doc/user/workflow/groups/transfer_project.png b/doc/user/workflow/groups/transfer_project.png Binary files differnew file mode 100644 index 00000000000..044fe10d073 --- /dev/null +++ b/doc/user/workflow/groups/transfer_project.png diff --git a/doc/user/workflow/groups/withdraw_access_request_button.png b/doc/user/workflow/groups/withdraw_access_request_button.png Binary files differnew file mode 100644 index 00000000000..99d7a326ed8 --- /dev/null +++ b/doc/user/workflow/groups/withdraw_access_request_button.png diff --git a/doc/user/workflow/img/award_emoji_select.png b/doc/user/workflow/img/award_emoji_select.png Binary files differnew file mode 100644 index 00000000000..fffdfedda5d --- /dev/null +++ b/doc/user/workflow/img/award_emoji_select.png diff --git a/doc/user/workflow/img/award_emoji_votes_least_popular.png b/doc/user/workflow/img/award_emoji_votes_least_popular.png Binary files differnew file mode 100644 index 00000000000..2ef5be7154f --- /dev/null +++ b/doc/user/workflow/img/award_emoji_votes_least_popular.png diff --git a/doc/user/workflow/img/award_emoji_votes_most_popular.png b/doc/user/workflow/img/award_emoji_votes_most_popular.png Binary files differnew file mode 100644 index 00000000000..5b089730d93 --- /dev/null +++ b/doc/user/workflow/img/award_emoji_votes_most_popular.png diff --git a/doc/user/workflow/img/award_emoji_votes_sort_options.png b/doc/user/workflow/img/award_emoji_votes_sort_options.png Binary files differnew file mode 100644 index 00000000000..9bbf3f82a0b --- /dev/null +++ b/doc/user/workflow/img/award_emoji_votes_sort_options.png diff --git a/doc/user/workflow/img/cherry_pick_changes_commit.png b/doc/user/workflow/img/cherry_pick_changes_commit.png Binary files differnew file mode 100644 index 00000000000..ae91d2cae53 --- /dev/null +++ b/doc/user/workflow/img/cherry_pick_changes_commit.png diff --git a/doc/user/workflow/img/cherry_pick_changes_commit_modal.png b/doc/user/workflow/img/cherry_pick_changes_commit_modal.png Binary files differnew file mode 100644 index 00000000000..f502f87677a --- /dev/null +++ b/doc/user/workflow/img/cherry_pick_changes_commit_modal.png diff --git a/doc/user/workflow/img/cherry_pick_changes_mr.png b/doc/user/workflow/img/cherry_pick_changes_mr.png Binary files differnew file mode 100644 index 00000000000..59c610e620b --- /dev/null +++ b/doc/user/workflow/img/cherry_pick_changes_mr.png diff --git a/doc/user/workflow/img/cherry_pick_changes_mr_modal.png b/doc/user/workflow/img/cherry_pick_changes_mr_modal.png Binary files differnew file mode 100644 index 00000000000..96a80f4726d --- /dev/null +++ b/doc/user/workflow/img/cherry_pick_changes_mr_modal.png diff --git a/doc/user/workflow/img/file_finder_find_button.png b/doc/user/workflow/img/file_finder_find_button.png Binary files differnew file mode 100644 index 00000000000..c5005d0d7ca --- /dev/null +++ b/doc/user/workflow/img/file_finder_find_button.png diff --git a/doc/user/workflow/img/file_finder_find_file.png b/doc/user/workflow/img/file_finder_find_file.png Binary files differnew file mode 100644 index 00000000000..58500f4c163 --- /dev/null +++ b/doc/user/workflow/img/file_finder_find_file.png diff --git a/doc/user/workflow/img/forking_workflow_choose_namespace.png b/doc/user/workflow/img/forking_workflow_choose_namespace.png Binary files differnew file mode 100644 index 00000000000..eefe5769554 --- /dev/null +++ b/doc/user/workflow/img/forking_workflow_choose_namespace.png diff --git a/doc/user/workflow/img/forking_workflow_fork_button.png b/doc/user/workflow/img/forking_workflow_fork_button.png Binary files differnew file mode 100644 index 00000000000..49e68d33e89 --- /dev/null +++ b/doc/user/workflow/img/forking_workflow_fork_button.png diff --git a/doc/user/workflow/img/forking_workflow_path_taken_error.png b/doc/user/workflow/img/forking_workflow_path_taken_error.png Binary files differnew file mode 100644 index 00000000000..7a3139506fe --- /dev/null +++ b/doc/user/workflow/img/forking_workflow_path_taken_error.png diff --git a/doc/user/workflow/img/new_branch_from_issue.png b/doc/user/workflow/img/new_branch_from_issue.png Binary files differnew file mode 100644 index 00000000000..394c139e17e --- /dev/null +++ b/doc/user/workflow/img/new_branch_from_issue.png diff --git a/doc/user/workflow/img/revert_changes_commit.png b/doc/user/workflow/img/revert_changes_commit.png Binary files differnew file mode 100644 index 00000000000..d84211e20db --- /dev/null +++ b/doc/user/workflow/img/revert_changes_commit.png diff --git a/doc/user/workflow/img/revert_changes_commit_modal.png b/doc/user/workflow/img/revert_changes_commit_modal.png Binary files differnew file mode 100644 index 00000000000..e94d151a2af --- /dev/null +++ b/doc/user/workflow/img/revert_changes_commit_modal.png diff --git a/doc/user/workflow/img/revert_changes_mr.png b/doc/user/workflow/img/revert_changes_mr.png Binary files differnew file mode 100644 index 00000000000..7adad88463b --- /dev/null +++ b/doc/user/workflow/img/revert_changes_mr.png diff --git a/doc/user/workflow/img/revert_changes_mr_modal.png b/doc/user/workflow/img/revert_changes_mr_modal.png Binary files differnew file mode 100644 index 00000000000..9da78f84828 --- /dev/null +++ b/doc/user/workflow/img/revert_changes_mr_modal.png diff --git a/doc/user/workflow/img/todos_icon.png b/doc/user/workflow/img/todos_icon.png Binary files differnew file mode 100644 index 00000000000..879b3b51c21 --- /dev/null +++ b/doc/user/workflow/img/todos_icon.png diff --git a/doc/user/workflow/img/todos_index.png b/doc/user/workflow/img/todos_index.png Binary files differnew file mode 100644 index 00000000000..4ee18dd1285 --- /dev/null +++ b/doc/user/workflow/img/todos_index.png diff --git a/doc/user/workflow/img/web_editor_new_branch_dropdown.png b/doc/user/workflow/img/web_editor_new_branch_dropdown.png Binary files differnew file mode 100644 index 00000000000..009e4b05adf --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_branch_dropdown.png diff --git a/doc/user/workflow/img/web_editor_new_branch_page.png b/doc/user/workflow/img/web_editor_new_branch_page.png Binary files differnew file mode 100644 index 00000000000..dd6cfc6e7bb --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_branch_page.png diff --git a/doc/user/workflow/img/web_editor_new_directory_dialog.png b/doc/user/workflow/img/web_editor_new_directory_dialog.png Binary files differnew file mode 100644 index 00000000000..2c76f84f395 --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_directory_dialog.png diff --git a/doc/user/workflow/img/web_editor_new_directory_dropdown.png b/doc/user/workflow/img/web_editor_new_directory_dropdown.png Binary files differnew file mode 100644 index 00000000000..cedf46aedfd --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_directory_dropdown.png diff --git a/doc/user/workflow/img/web_editor_new_file_dropdown.png b/doc/user/workflow/img/web_editor_new_file_dropdown.png Binary files differnew file mode 100644 index 00000000000..6e884f6504d --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_file_dropdown.png diff --git a/doc/user/workflow/img/web_editor_new_file_editor.png b/doc/user/workflow/img/web_editor_new_file_editor.png Binary files differnew file mode 100644 index 00000000000..c76473bcfa7 --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_file_editor.png diff --git a/doc/user/workflow/img/web_editor_new_push_widget.png b/doc/user/workflow/img/web_editor_new_push_widget.png Binary files differnew file mode 100644 index 00000000000..a2108735741 --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_push_widget.png diff --git a/doc/user/workflow/img/web_editor_new_tag_dropdown.png b/doc/user/workflow/img/web_editor_new_tag_dropdown.png Binary files differnew file mode 100644 index 00000000000..263dd635b95 --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_tag_dropdown.png diff --git a/doc/user/workflow/img/web_editor_new_tag_page.png b/doc/user/workflow/img/web_editor_new_tag_page.png Binary files differnew file mode 100644 index 00000000000..64d7cd11ed1 --- /dev/null +++ b/doc/user/workflow/img/web_editor_new_tag_page.png diff --git a/doc/user/workflow/img/web_editor_start_new_merge_request.png b/doc/user/workflow/img/web_editor_start_new_merge_request.png Binary files differnew file mode 100644 index 00000000000..be12a151cac --- /dev/null +++ b/doc/user/workflow/img/web_editor_start_new_merge_request.png diff --git a/doc/user/workflow/img/web_editor_upload_file_dialog.png b/doc/user/workflow/img/web_editor_upload_file_dialog.png Binary files differnew file mode 100644 index 00000000000..6dd2207bca0 --- /dev/null +++ b/doc/user/workflow/img/web_editor_upload_file_dialog.png diff --git a/doc/user/workflow/img/web_editor_upload_file_dropdown.png b/doc/user/workflow/img/web_editor_upload_file_dropdown.png Binary files differnew file mode 100644 index 00000000000..bf6528701b0 --- /dev/null +++ b/doc/user/workflow/img/web_editor_upload_file_dropdown.png diff --git a/doc/user/workflow/importing/README.md b/doc/user/workflow/importing/README.md new file mode 100644 index 00000000000..18e5d950866 --- /dev/null +++ b/doc/user/workflow/importing/README.md @@ -0,0 +1,17 @@ +# Migrating projects to a GitLab instance
+
+1. [Bitbucket](import_projects_from_bitbucket.md)
+1. [GitHub](import_projects_from_github.md)
+1. [GitLab.com](import_projects_from_gitlab_com.md)
+1. [FogBugz](import_projects_from_fogbugz.md)
+1. [SVN](migrating_from_svn.md)
+
+In addition to the specific migration documentation above, you can import any
+Git repository via HTTP from the New Project page. Be aware that if the
+repository is too large the import can timeout.
+
+### Migrating from self-hosted GitLab to GitLab.com
+
+You can copy your repos by changing the remote and pushing to the new server;
+but issues and merge requests can't be imported.
+
diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png Binary files differnew file mode 100644 index 00000000000..df55a081803 --- /dev/null +++ b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png Binary files differnew file mode 100644 index 00000000000..5253889d251 --- /dev/null +++ b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png Binary files differnew file mode 100644 index 00000000000..ffa87ce5b2e --- /dev/null +++ b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png Binary files differnew file mode 100644 index 00000000000..0e08703f421 --- /dev/null +++ b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png Binary files differnew file mode 100644 index 00000000000..205c515bd3f --- /dev/null +++ b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png Binary files differnew file mode 100644 index 00000000000..a1e348d46ad --- /dev/null +++ b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png Binary files differnew file mode 100644 index 00000000000..ed362846909 --- /dev/null +++ b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png Binary files differnew file mode 100644 index 00000000000..d2fbd0267bd --- /dev/null +++ b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png Binary files differnew file mode 100644 index 00000000000..b1cc4b58525 --- /dev/null +++ b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png diff --git a/doc/user/workflow/importing/gitlab_importer/importer.png b/doc/user/workflow/importing/gitlab_importer/importer.png Binary files differnew file mode 100644 index 00000000000..d2a286d8cac --- /dev/null +++ b/doc/user/workflow/importing/gitlab_importer/importer.png diff --git a/doc/user/workflow/importing/gitlab_importer/new_project_page.png b/doc/user/workflow/importing/gitlab_importer/new_project_page.png Binary files differnew file mode 100644 index 00000000000..5e239208e1e --- /dev/null +++ b/doc/user/workflow/importing/gitlab_importer/new_project_page.png diff --git a/doc/user/workflow/importing/img/import_projects_from_github_importer.png b/doc/user/workflow/importing/img/import_projects_from_github_importer.png Binary files differnew file mode 100644 index 00000000000..f744dc06f81 --- /dev/null +++ b/doc/user/workflow/importing/img/import_projects_from_github_importer.png diff --git a/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png Binary files differnew file mode 100644 index 00000000000..86be35acb37 --- /dev/null +++ b/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png diff --git a/doc/user/workflow/importing/import_projects_from_bitbucket.md b/doc/user/workflow/importing/import_projects_from_bitbucket.md new file mode 100644 index 00000000000..520c4216295 --- /dev/null +++ b/doc/user/workflow/importing/import_projects_from_bitbucket.md @@ -0,0 +1,26 @@ +# Import your project from Bitbucket to GitLab
+
+It takes just a few steps to import your existing Bitbucket projects to GitLab. But keep in mind that it is possible only if Bitbucket support is enabled on your GitLab instance. You can read more about Bitbucket support [here](../../integration/bitbucket.md).
+
+* Sign in to GitLab.com and go to your dashboard
+
+* Click on "New project"
+
+
+
+* Click on the "Bitbucket" button
+
+
+
+* Grant GitLab access to your Bitbucket account
+
+
+
+* Click on the projects that you'd like to import or "Import all projects"
+
+
+
+A new GitLab project will be created with your imported data.
+
+### Note
+Milestones and wiki pages are not imported from Bitbucket.
diff --git a/doc/user/workflow/importing/import_projects_from_fogbugz.md b/doc/user/workflow/importing/import_projects_from_fogbugz.md new file mode 100644 index 00000000000..71af0f9ea44 --- /dev/null +++ b/doc/user/workflow/importing/import_projects_from_fogbugz.md @@ -0,0 +1,29 @@ +# Import your project from FogBugz to GitLab + +It only takes a few simple steps to import your project from FogBugz. +The importer will import all of your cases and comments with original case +numbers and timestamps. You will also have the opportunity to map FogBugz +users to GitLab users. + +* From your GitLab dashboard click 'New project' + +* Click on the 'FogBugz' button + + + +* Enter your FogBugz URL, email address, and password. + + + +* Create mapping from FogBugz users to GitLab users. + + + +* Select the projects you wish to import by clicking the Import buttons + + + +* Once the import has finished click the link to take you to the project +dashboard. Follow the directions to push your existing repository. + + diff --git a/doc/user/workflow/importing/import_projects_from_github.md b/doc/user/workflow/importing/import_projects_from_github.md new file mode 100644 index 00000000000..a7dfac2c120 --- /dev/null +++ b/doc/user/workflow/importing/import_projects_from_github.md @@ -0,0 +1,48 @@ +# Import your project from GitHub to GitLab
+
+>**Note:**
+In order to enable the GitHub import setting, you should first
+enable the [GitHub integration][gh-import] in your GitLab instance.
+
+At its current state, GitHub importer can import:
+
+- the repository description (introduced in GitLab 7.7)
+- the git repository data (introduced in GitLab 7.7)
+- the issues (introduced in GitLab 7.7)
+- the pull requests (introduced in GitLab 8.4)
+- the wiki pages (introduced in GitLab 8.4)
+- the milestones (introduced in GitLab 8.7)
+- the labels (introduced in GitLab 8.7)
+
+With GitLab 8.7+, references to pull requests and issues are preserved.
+
+It is not yet possible to import your cross-repository pull requests (those from
+forks). We are working on improving this in the near future.
+
+The importer page is visible when you [create a new project][new-project].
+Click on the **GitHub** link and you will be redirected to GitHub for
+permission to access your projects. After accepting, you'll be automatically
+redirected to the importer.
+
+
+
+---
+
+While at the GitHub importer page, you can see the import statuses of your
+GitHub projects. Those that are being imported will show a _started_ status,
+those already imported will be green, whereas those that are not yet imported
+have an **Import** button on the right side of the table. If you want, you can
+import all your GitHub projects in one go by hitting **Import all projects**
+in the upper left corner.
+
+
+
+---
+
+The importer will create any new namespaces if they don't exist or in the
+case the namespace is taken, the project will be imported on the user's
+namespace.
+
+[gh-import]: ../../integration/github.md "GitHub integration"
+[ee-gh]: http://docs.gitlab.com/ee/integration/github.html "GitHub integration for GitLab EE"
+[new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"
diff --git a/doc/user/workflow/importing/import_projects_from_gitlab_com.md b/doc/user/workflow/importing/import_projects_from_gitlab_com.md new file mode 100644 index 00000000000..dcc00074b75 --- /dev/null +++ b/doc/user/workflow/importing/import_projects_from_gitlab_com.md @@ -0,0 +1,18 @@ +# Project importing from GitLab.com to your private GitLab instance + +You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if +GitLab support is enabled on your GitLab instance. +You can read more about GitLab support [here](http://docs.gitlab.com/ce/integration/gitlab.html) +To get to the importer page you need to go to "New project" page. + + + +Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com +for permission to access your projects. After accepting, you'll be automatically redirected to the importer. + + + + + +To import a project, you can simple click "Import". The importer will import your repository and issues. +Once the importer is done, a new GitLab project will be created with your imported data.
\ No newline at end of file diff --git a/doc/user/workflow/importing/migrating_from_svn.md b/doc/user/workflow/importing/migrating_from_svn.md new file mode 100644 index 00000000000..4828bb5dce6 --- /dev/null +++ b/doc/user/workflow/importing/migrating_from_svn.md @@ -0,0 +1,79 @@ +# Migrating from SVN to GitLab + +Subversion (SVN) is a central version control system (VCS) while +Git is a distributed version control system. There are some major differences +between the two, for more information consult your favorite search engine. + +If you are currently using an SVN repository, you can migrate the repository +to Git and GitLab. We recommend a hard cut over - run the migration command once +and then have all developers start using the new GitLab repository immediately. +Otherwise, it's hard to keep changing in sync in both directions. The conversion +process should be run on a local workstation. + +Install `svn2git`. On all systems you can install as a Ruby gem if you already +have Ruby and Git installed. + +```bash +sudo gem install svn2git +``` + +On Debian-based Linux distributions you can install the native packages: + +```bash +sudo apt-get install git-core git-svn ruby +``` + +Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. +If you choose not to create the authors file then commits will not be attributed +to the correct GitLab user. Some users may not consider this a big issue while +others will want to ensure they complete this step. If you choose to map authors +you will be required to map every author that is present on changes in the SVN +repository. If you don't, the conversion will fail and you will have to update +the author file accordingly. The following command will search through the +repository and output a list of authors. + +```bash +svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq +``` + +Use the output from the last command to construct the authors file. +Create a file called `authors.txt` and add one mapping per line. + +``` +janedoe = Jane Doe <janedoe@example.com> +johndoe = John Doe <johndoe@example.com> +``` + +If your SVN repository is in the standard format (trunk, branches, tags, +not nested) the conversion is simple. For a non-standard repository see +[svn2git documentation](https://github.com/nirvdrum/svn2git). The following +command will checkout the repository and do the conversion in the current +working directory. Be sure to create a new directory for each repository before +running the `svn2git` command. The conversion process will take some time. + +```bash +svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt +``` + +If your SVN repository requires a username and password add the +`--username <username>` and `--password <password` flags to the above command. +`svn2git` also supports excluding certain file paths, branches, tags, etc. See +[svn2git documentation](https://github.com/nirvdrum/svn2git) or run +`svn2git --help` for full documentation on all of the available options. + +Create a new GitLab project, where you will eventually push your converted code. +Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab +repository as a Git remote and push all the changes. This will push all commits, +branches and tags. + +```bash +git remote add origin git@gitlab.com:<group>/<project>.git +git push --all origin +git push --tags origin +``` + +## Contribute to this guide +We welcome all contributions that would expand this guide with instructions on +how to migrate from SVN and other version control systems. + + diff --git a/doc/user/workflow/labels.md b/doc/user/workflow/labels.md new file mode 100644 index 00000000000..6e4840ca5ae --- /dev/null +++ b/doc/user/workflow/labels.md @@ -0,0 +1,18 @@ +# Labels + +In GitLab, you can easily tag issues and Merge Requests. If you have permission level `Developer` or higher, you can manage labels. To create, edit or delete a label, go to a project and then to `Issues` and then `Labels`. + +Here you can create a new label. + + + +You can choose to set a color. + + + +If you want to change an existing label, press edit next to the listed label. +You will be presented with the same form as when creating a new label. + + + +You can add labels to Merge Requests when you create or edit them. diff --git a/doc/user/workflow/labels/label1.png b/doc/user/workflow/labels/label1.png Binary files differnew file mode 100644 index 00000000000..cac661a34c8 --- /dev/null +++ b/doc/user/workflow/labels/label1.png diff --git a/doc/user/workflow/labels/label2.png b/doc/user/workflow/labels/label2.png Binary files differnew file mode 100644 index 00000000000..44d9fef86d4 --- /dev/null +++ b/doc/user/workflow/labels/label2.png diff --git a/doc/user/workflow/labels/label3.png b/doc/user/workflow/labels/label3.png Binary files differnew file mode 100644 index 00000000000..e2fce11b7a4 --- /dev/null +++ b/doc/user/workflow/labels/label3.png diff --git a/doc/user/workflow/lfs/lfs_administration.md b/doc/user/workflow/lfs/lfs_administration.md new file mode 100644 index 00000000000..9dc1e9b47e3 --- /dev/null +++ b/doc/user/workflow/lfs/lfs_administration.md @@ -0,0 +1,49 @@ +# GitLab Git LFS Administration + +Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](manage_large_binaries_with_git_lfs.md). + +## Requirements + +* Git LFS is supported in GitLab starting with version 8.2. +* Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. + +## Configuration + +Git LFS objects can be large in size. By default, they are stored on the server +GitLab is installed on. + +There are two configuration options to help GitLab server administrators: + +* Enabling/disabling Git LFS support +* Changing the location of LFS object storage + +### Omnibus packages + +In `/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_rails['lfs_enabled'] = false + +# Optionally, change the storage path location. Defaults to +# `#{gitlab_rails['shared_path']}/lfs-objects`. Which evaluates to +# `/var/opt/gitlab/gitlab-rails/shared/lfs-objects` by default. +gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" +``` + +### Installations from source + +In `config/gitlab.yml`: + +```yaml + lfs: + enabled: false + storage_path: /mnt/storage/lfs-objects +``` + +## Known limitations + +* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) + is not supported +* Currently, removing LFS objects from GitLab Git LFS storage is not supported +* LFS authentications via SSH is not supported for the time being +* Only compatible with the GitLFS client versions 1.1.0 or 1.0.2. diff --git a/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md new file mode 100644 index 00000000000..9fe065fa680 --- /dev/null +++ b/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -0,0 +1,155 @@ +# Git LFS + +Managing large files such as audio, video and graphics files has always been one +of the shortcomings of Git. The general recommendation is to not have Git repositories +larger than 1GB to preserve performance. + +GitLab already supports [managing large files with git annex](http://docs.gitlab.com/ee/workflow/git_annex.html) +(EE only), however in certain environments it is not always convenient to use +different commands to differentiate between the large files and regular ones. + +Git LFS makes this simpler for the end user by removing the requirement to +learn new commands. + +## 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 +instructions from where to fetch or where to push the large file. + +## GitLab server configuration + +Documentation for GitLab instance administrators is under [LFS administration doc](lfs_administration.md). + +## Requirements + +* Git LFS is supported in GitLab starting with version 8.2 +* [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up + +## 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 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) + +## Using Git LFS + +Lets take a look at the workflow when you need to check large files into your Git +repository with Git LFS. For example, if you want to upload a very large file and +check it into your Git repository: + +```bash +git clone git@gitlab.example.com:group/project.git +git lfs install # initialize the Git LFS project 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: + +```bash +cp ~/tmp/debian.iso ./ # copy a large file into the current directory +git add . # add the large file to the project +git commit -am "Added Debian iso" # commit the file meta data +git push origin master # sync the git repo and large file to the GitLab server +``` + +Cloning the repository works the same as before. Git automatically detects the +LFS-tracked files and clones them via HTTP. If you performed the git clone +command with a SSH URL, you have to enter your GitLab credentials for HTTP +authentication. + +```bash +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. from branch `master`: + +```bash +git lfs fetch master +``` + +## Troubleshooting + +### error: Repository or object not found + +There are a couple of reasons why this error can occur: + +* You don't have permissions to access certain LFS object + +Check if you have permissions to push to the project or fetch from the project. + +* Project is not allowed to access the LFS object + +LFS object you are trying to push to the project or fetch from the project is not +available to the project anymore. Probably the object was removed from the server. + +* Local git repository is using deprecated LFS API + +### Invalid status for <url> : 501 + +Git LFS will log the failures into a log file. +To view this log file, while in project directory: + +```bash +git lfs logs last +``` + +If the status `error 501` is shown, it is because: + +* Git LFS support is not enabled on the GitLab server. Check with your GitLab + administrator why Git LFS is not enabled on the server. See + [LFS administration documentation](lfs_administration.md) for instructions + 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, + remove the line and try to update your Git LFS client. Only version 1.0.1 and + newer are supported. + +### 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`, +the LFS client is trying to reach GitLab through HTTPS. However, your GitLab +instance is being served on HTTP. + +This behaviour is caused by Git LFS using HTTPS connections by default when a +`lfsurl` is not set in the Git config. + +To prevent this from happening, set the lfs url in project Git config: + +```bash + +git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" +``` + +### Credentials are always required when pushing an object + +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. + +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). + +For example, you can tell Git to remember the password for a period of time in +which you expect to push the objects: + +```bash +git config --global credential.helper 'cache --timeout=3600' +``` + +This will remember the credentials for an hour after which Git operations will +require re-authentication. + +If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. +For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases). + +More details about various methods of storing the user credentials can be found +on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). diff --git a/doc/user/workflow/merge_commits.png b/doc/user/workflow/merge_commits.png Binary files differnew file mode 100644 index 00000000000..757b589d0db --- /dev/null +++ b/doc/user/workflow/merge_commits.png diff --git a/doc/user/workflow/merge_request.png b/doc/user/workflow/merge_request.png Binary files differnew file mode 100644 index 00000000000..fde3ff5c854 --- /dev/null +++ b/doc/user/workflow/merge_request.png diff --git a/doc/user/workflow/merge_requests.md b/doc/user/workflow/merge_requests.md new file mode 100644 index 00000000000..d2ec56e6504 --- /dev/null +++ b/doc/user/workflow/merge_requests.md @@ -0,0 +1,63 @@ +# Merge Requests + +Merge requests allow you to exchange changes you made to source code + +## Only allow merge requests to be merged if the build succeeds + +You can prevent merge requests from being merged if their build did not succeed +in the project settings page. + + + +Navigate to project settings page and select the `Only allow merge requests to be merged if the build succeeds` check box. + +Please note that you need to have builds configured to enable this feature. + +## Checkout merge requests locally + +Locate the section for your GitLab remote in the `.git/config` file. It looks like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-ce.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section. + +It should look like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-ce.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests requests: + +``` +$ git fetch origin +From https://gitlab.com/gitlab-org/gitlab-ce.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +To check out a particular merge request: + +``` +$ git checkout origin/merge-requests/1 +``` + +## Ignore whitespace changes in Merge Request diff view + + + +If you click the "Hide whitespace changes" button, you can see the diff without whitespace changes. + + + +It is also working on commits compare view. + + diff --git a/doc/user/workflow/merge_requests/commit_compare.png b/doc/user/workflow/merge_requests/commit_compare.png Binary files differnew file mode 100644 index 00000000000..dfd7ee220f0 --- /dev/null +++ b/doc/user/workflow/merge_requests/commit_compare.png diff --git a/doc/user/workflow/merge_requests/merge_request_diff.png b/doc/user/workflow/merge_requests/merge_request_diff.png Binary files differnew file mode 100644 index 00000000000..f368423c746 --- /dev/null +++ b/doc/user/workflow/merge_requests/merge_request_diff.png diff --git a/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png b/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png Binary files differnew file mode 100644 index 00000000000..b2d03bb66f9 --- /dev/null +++ b/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png diff --git a/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png b/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png Binary files differnew file mode 100644 index 00000000000..18bebf5fe92 --- /dev/null +++ b/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png diff --git a/doc/user/workflow/merge_when_build_succeeds.md b/doc/user/workflow/merge_when_build_succeeds.md new file mode 100644 index 00000000000..75e1fdff2b2 --- /dev/null +++ b/doc/user/workflow/merge_when_build_succeeds.md @@ -0,0 +1,15 @@ +# Merge When Build Succeeds + +When reviewing a merge request that looks ready to merge but still has one or more CI builds running, you can set it to be merged automatically when all builds succeed. This way, you don't have to wait for the builds to finish and remember to merge the request manually. + + + +When you hit the "Merge When Build Succeeds" button, the status of the merge request will be updated to represent the impending merge. If you cannot wait for the build to succeed and want to merge immediately, this option is available in the dropdown menu on the right of the main button. + +Both team developers and the author of the merge request have the option to cancel the automatic merge if they find a reason why it shouldn't be merged after all. + + + +When the build succeeds, the merge request will automatically be merged. When the build fails, the author gets a chance to retry any failed builds, or to push new commits to fix the failure. + +When the builds are retried and succeed on the second try, the merge request will automatically be merged after all. When the merge request is updated with new commits, the automatic merge is automatically canceled to allow the new changes to be reviewed. diff --git a/doc/user/workflow/merge_when_build_succeeds/enable.png b/doc/user/workflow/merge_when_build_succeeds/enable.png Binary files differnew file mode 100644 index 00000000000..633efa1246f --- /dev/null +++ b/doc/user/workflow/merge_when_build_succeeds/enable.png diff --git a/doc/user/workflow/merge_when_build_succeeds/status.png b/doc/user/workflow/merge_when_build_succeeds/status.png Binary files differnew file mode 100644 index 00000000000..c856c7d14dc --- /dev/null +++ b/doc/user/workflow/merge_when_build_succeeds/status.png diff --git a/doc/user/workflow/messy_flow.png b/doc/user/workflow/messy_flow.png Binary files differnew file mode 100644 index 00000000000..1addb95ca54 --- /dev/null +++ b/doc/user/workflow/messy_flow.png diff --git a/doc/user/workflow/milestones.md b/doc/user/workflow/milestones.md new file mode 100644 index 00000000000..dff36899aec --- /dev/null +++ b/doc/user/workflow/milestones.md @@ -0,0 +1,13 @@ +# Milestones + +Milestones allow you to organize issues and merge requests into a cohesive group, optionally setting a due date. +A common use is keeping track of an upcoming software version. Milestones are created per-project. + + + +## Groups and milestones + +You can create a milestone for several projects in the same group simultaneously. +On the group's milestones page, you will be able to see the status of that milestone across all of the selected projects. + + diff --git a/doc/user/workflow/milestones/form.png b/doc/user/workflow/milestones/form.png Binary files differnew file mode 100644 index 00000000000..de44c1ffc1a --- /dev/null +++ b/doc/user/workflow/milestones/form.png diff --git a/doc/user/workflow/milestones/group_form.png b/doc/user/workflow/milestones/group_form.png Binary files differnew file mode 100644 index 00000000000..38862dcca68 --- /dev/null +++ b/doc/user/workflow/milestones/group_form.png diff --git a/doc/user/workflow/mr_inline_comments.png b/doc/user/workflow/mr_inline_comments.png Binary files differnew file mode 100644 index 00000000000..e851b95bcef --- /dev/null +++ b/doc/user/workflow/mr_inline_comments.png diff --git a/doc/user/workflow/notifications.md b/doc/user/workflow/notifications.md new file mode 100644 index 00000000000..fe4485e148a --- /dev/null +++ b/doc/user/workflow/notifications.md @@ -0,0 +1,93 @@ +# GitLab Notification Emails + +GitLab has a notification system in place to notify a user of events that are important for the workflow. + +## Notification settings + +You can find notification settings under the user profile. + + + +Notification settings are divided into three groups: + +* Global Settings +* Group Settings +* Project Settings + +Each of these settings have levels of notification: + +* Disabled - turns off notifications +* Participating - receive notifications from related resources +* Watch - receive notifications from projects or groups user is a member of +* Global - notifications as set at the global settings +* Custom - user will receive notifications when mentioned, is participant and custom selected events. + +#### Global Settings + +Global Settings are at the bottom of the hierarchy. +Any setting set here will be overridden by a setting at the group or a project level. + +Group or Project settings can use `global` notification setting which will then use +anything that is set at Global Settings. + +#### Group Settings + +Group Settings are taking precedence over Global Settings but are on a level below Project Settings. +This means that you can set a different level of notifications per group while still being able +to have a finer level setting per project. +Organization like this is suitable for users that belong to different groups but don't have the +same need for being notified for every group they are member of. + +#### Project Settings + +Project Settings are at the top level and any setting placed at this level will take precedence of any +other setting. +This is suitable for users that have different needs for notifications per project basis. + +## Notification events + +Below is the table of events users can be notified of: + +| Event | Sent to | Settings level | +|------------------------------|-------------------------------------------------------------------|------------------------------| +| New SSH key added | User | Security email, always sent. | +| New email added | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for omniauth (LDAP)| +| User added to project | User | Sent when user is added to project | +| Project access level changed | User | Sent when user project access level is changed | +| User added to group | User | Sent when user is added to group | +| Group access level changed | User | Sent when user group access level is changed | +| Project moved | Project members [1] | [1] not disabled | + +### Issue / Merge Request events + +In all of the below cases, the notification will be sent to: +- Participants: + - the author and assignee of the issue/merge request + - authors of comments on the issue/merge request + - anyone mentioned by `@username` in the issue/merge request description + - anyone mentioned by `@username` in any of the comments on the issue/merge request + + ...with notification level "Participating" or higher + +- Watchers: users with notification level "Watch" +- Subscribers: anyone who manually subscribed to the issue/merge request +- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below + +| Event | Sent to | +|------------------------|---------| +| New issue | | +| Close issue | | +| Reassign issue | The above, plus the old assignee | +| Reopen issue | | +| New merge request | | +| Reassign merge request | The above, plus the old assignee | +| Close merge request | | +| Reopen merge request | | +| Merge merge request | | +| New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | + +You won't receive notifications for Issues, Merge Requests or Milestones +created by yourself. You will only receive automatic notifications when +somebody else comments or adds changes to the ones that you've created or +mentions you. diff --git a/doc/user/workflow/notifications/settings.png b/doc/user/workflow/notifications/settings.png Binary files differnew file mode 100644 index 00000000000..7c6857aad1a --- /dev/null +++ b/doc/user/workflow/notifications/settings.png diff --git a/doc/user/workflow/production_branch.png b/doc/user/workflow/production_branch.png Binary files differnew file mode 100644 index 00000000000..33fb26dd621 --- /dev/null +++ b/doc/user/workflow/production_branch.png diff --git a/doc/user/workflow/project_features.md b/doc/user/workflow/project_features.md new file mode 100644 index 00000000000..a523b3facbe --- /dev/null +++ b/doc/user/workflow/project_features.md @@ -0,0 +1,35 @@ +# Project features + +When in a Project -> Settings, you will find Features on the bottom of the page that you can toggle. + +Below you will find a more elaborate explanation of each of these. + +## Issues + +Issues is a really powerful, but lightweight issue tracking system. + +You can make tickets, assign them to people, file them under milestones, order them with labels and have discussion in them. + +They integrate deeply into GitLab and are easily referenced from anywhere by using `#` and the issue number. + +## Merge Requests + +Using a merge request, you can review and discuss code before it is merged in the branch of your code. + +As with issues, it can be assigned; people, issues, etc. can be referenced; milestones attached. + +We see it as an integral part of working together on code and couldn't work without it. + +## Wiki + +This is a separate system for documentation, built right into GitLab. + +It is source controlled and is very convenient if you don't want to keep you documentation in your source code, but you do want to keep it in your GitLab project. + +## Snippets + +Snippets are little bits of code or text. + +This is a nice place to put code or text that is used semi-regularly within the project, but does not belong in source control. + +For example, a specific config file that is used by > the team that is only valid for the people that work on the code. diff --git a/doc/user/workflow/protected_branches.md b/doc/user/workflow/protected_branches.md new file mode 100644 index 00000000000..d854ec1e025 --- /dev/null +++ b/doc/user/workflow/protected_branches.md @@ -0,0 +1,31 @@ +# Protected branches + +Permissions in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. + +To prevent people from messing with history or pushing code without review, we've created protected branches. + +A protected branch does three simple things: + +* it prevents pushes from everybody except users with Master permission +* it prevents anyone from force pushing to the branch +* it prevents anyone from deleting the branch + +You can make any branch a protected branch. GitLab makes the master branch a protected branch by default. + +To protect a branch, user needs to have at least a Master permission level, see [permissions document](../permissions/permissions.md). + + + +Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect. + +Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch. + +Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request. + +However, there are workflows where that is not needed and only protecting from force pushes and branch removal is useful. + +For those workflows, you can allow everyone with write access to push to a protected branch by selecting `Developers can push` check box. + +On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box. + +
\ No newline at end of file diff --git a/doc/user/workflow/protected_branches/protected_branches1.png b/doc/user/workflow/protected_branches/protected_branches1.png Binary files differnew file mode 100644 index 00000000000..5c2a3de5f70 --- /dev/null +++ b/doc/user/workflow/protected_branches/protected_branches1.png diff --git a/doc/user/workflow/protected_branches/protected_branches2.png b/doc/user/workflow/protected_branches/protected_branches2.png Binary files differnew file mode 100644 index 00000000000..2dca3541365 --- /dev/null +++ b/doc/user/workflow/protected_branches/protected_branches2.png diff --git a/doc/user/workflow/rebase.png b/doc/user/workflow/rebase.png Binary files differnew file mode 100644 index 00000000000..ef82c834755 --- /dev/null +++ b/doc/user/workflow/rebase.png diff --git a/doc/user/workflow/release_branches.png b/doc/user/workflow/release_branches.png Binary files differnew file mode 100644 index 00000000000..da7ae53413a --- /dev/null +++ b/doc/user/workflow/release_branches.png diff --git a/doc/user/workflow/releases.md b/doc/user/workflow/releases.md new file mode 100644 index 00000000000..6176784fc57 --- /dev/null +++ b/doc/user/workflow/releases.md @@ -0,0 +1,20 @@ +# Releases + +You can turn any git tag into a release, by adding a note to it. +Release notes behave like any other markdown form in GitLab so you can write text and drag-n-drop files to it. +Release notes are stored in the database of GitLab. + +There are several ways to add release notes: + +* In the interface, when you create a new git tag with GitLab +* In the interface, by adding a note to an existing git tag +* with the GitLab API + +## New tag page with release notes text area + + + +## Tags page with button to add or edit release notes for existing git tag + + + diff --git a/doc/user/workflow/releases/new_tag.png b/doc/user/workflow/releases/new_tag.png Binary files differnew file mode 100644 index 00000000000..e2b64bfe17f --- /dev/null +++ b/doc/user/workflow/releases/new_tag.png diff --git a/doc/user/workflow/releases/tags.png b/doc/user/workflow/releases/tags.png Binary files differnew file mode 100644 index 00000000000..aca91906c68 --- /dev/null +++ b/doc/user/workflow/releases/tags.png diff --git a/doc/user/workflow/remove_checkbox.png b/doc/user/workflow/remove_checkbox.png Binary files differnew file mode 100644 index 00000000000..3e247d38155 --- /dev/null +++ b/doc/user/workflow/remove_checkbox.png diff --git a/doc/user/workflow/revert_changes.md b/doc/user/workflow/revert_changes.md new file mode 100644 index 00000000000..399366b0cdc --- /dev/null +++ b/doc/user/workflow/revert_changes.md @@ -0,0 +1,64 @@ +# Reverting changes + +_**Note:** This feature was [introduced][ce-1990] in GitLab 8.5._ + +--- + +GitLab implements Git's powerful feature to [revert any commit][git-revert] +with introducing a **Revert** button in Merge Requests and commit details. + +## Reverting a Merge Request + +_**Note:** The **Revert** button will only be available for Merge Requests +created since GitLab 8.5. However, you can still revert a Merge Request +by reverting the merge commit from the list of Commits page._ + +After the Merge Request has been merged, a **Revert** button will be available +to revert the changes introduced by that Merge Request: + + + +--- + +You can revert the changes directly into the selected branch or you can opt to +create a new Merge Request with the revert changes: + + + +--- + +After the Merge Request has been reverted, the **Revert** button will not be +available anymore. + +## Reverting a Commit + +You can revert a Commit from the Commit details page: + + + +--- + +Similar to reverting a Merge Request, you can opt to revert the changes +directly into the target branch or create a new Merge Request to revert the +changes: + + + +--- + +After the Commit has been reverted, the **Revert** button will not be available +anymore. + +Please note that when reverting merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line. + +Here is a quick example to revert a merge commit using the second parent as the +mainline: + +```bash +git revert -m 2 7a39eb0 +``` + +[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request" +[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation" diff --git a/doc/user/workflow/share_projects_with_other_groups.md b/doc/user/workflow/share_projects_with_other_groups.md new file mode 100644 index 00000000000..4c59f59c587 --- /dev/null +++ b/doc/user/workflow/share_projects_with_other_groups.md @@ -0,0 +1,30 @@ +# Share Projects with other Groups + +In GitLab Enterprise Edition you can share projects with other groups. +This makes it possible to add a group of users to a project with a single action. + +## Groups as collections of users + +In GitLab Community Edition groups are used primarily to [create collections of projects](groups.md). +In GitLab Enterprise Edition you can also take advantage of the fact that groups define collections of _users_, namely the group members. + +## Sharing a project with a group of users + +The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project Acme'. +But what if 'Project Acme' already belongs to another group, say 'Open Source'? +This is where the (Enterprise Edition only) group sharing feature can be of use. + +To share 'Project Acme' with the 'Engineering' group, go to the project settings page for 'Project Acme' and use the left navigation menu to go to the 'Groups' section. + + + +Now you can add the 'Engineering' group with the maximum access level of your choice. +After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard. + + + +## Maximum access level + + + +In the screenshot above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Master' or 'Owner') will only have 'Developer' access to 'Project Acme'. diff --git a/doc/user/workflow/share_with_group.md b/doc/user/workflow/share_with_group.md new file mode 100644 index 00000000000..3b7690973cb --- /dev/null +++ b/doc/user/workflow/share_with_group.md @@ -0,0 +1,13 @@ +# Sharing a project with a group + +If you want to share a single project in a group with another group, +you can do so easily. By setting the permission you can quickly +give a select group of users access to a project in a restricted manner. + +In a project go to the project settings -> groups. + +Now you can select a group that you want to share this project with and with +which maximum access level. Users in that group are able to access this project +with their set group access level, up to the maximum level that you've set. + + diff --git a/doc/user/workflow/share_with_group.png b/doc/user/workflow/share_with_group.png Binary files differnew file mode 100644 index 00000000000..a0ca6f14552 --- /dev/null +++ b/doc/user/workflow/share_with_group.png diff --git a/doc/user/workflow/shortcuts.md b/doc/user/workflow/shortcuts.md new file mode 100644 index 00000000000..ffcb832cdd7 --- /dev/null +++ b/doc/user/workflow/shortcuts.md @@ -0,0 +1,5 @@ +# GitLab keyboard shortcuts + +You can see GitLab's keyboard shortcuts by using 'shift + ?' + +
\ No newline at end of file diff --git a/doc/user/workflow/shortcuts.png b/doc/user/workflow/shortcuts.png Binary files differnew file mode 100644 index 00000000000..16be0413b64 --- /dev/null +++ b/doc/user/workflow/shortcuts.png diff --git a/doc/user/workflow/timezone.md b/doc/user/workflow/timezone.md new file mode 100644 index 00000000000..7e08c0e51ac --- /dev/null +++ b/doc/user/workflow/timezone.md @@ -0,0 +1,30 @@ +# Changing your time zone + +The global time zone configuration parameter can be changed in `config/gitlab.yml`: +``` + # time_zone: 'UTC' +``` + +Uncomment and customize if you want to change the default time zone of GitLab application. + +To see all available time zones, run `bundle exec rake time:zones:all`. + + +## Changing time zone in omnibus installations + +GitLab defaults its time zone to UTC. It has a global timezone configuration parameter in `/etc/gitlab/gitlab.rb`. + +To update, add the time zone that best applies to your location. Here are two examples: +``` +gitlab_rails['time_zone'] = 'America/New_York' +``` +or +``` +gitlab_rails['time_zone'] = 'Europe/Brussels' +``` + +After you added this field, reconfigure and restart: +``` +gitlab-ctl reconfigure +gitlab-ctl restart +``` diff --git a/doc/user/workflow/todos.md b/doc/user/workflow/todos.md new file mode 100644 index 00000000000..5f440fdafdd --- /dev/null +++ b/doc/user/workflow/todos.md @@ -0,0 +1,73 @@ +# GitLab ToDos + +>**Note:** This feature was [introduced][ce-2817] in GitLab 8.5. + +When you log into GitLab, you normally want to see where you should spend your +time and take some action, or what you need to keep an eye on. All without the +mess of a huge pile of e-mail notifications. GitLab is where you do your work, +so being able to get started quickly is very important. + +Todos is a chronological list of to-dos that are waiting for your input, all +in a simple dashboard. + + + +--- + +You can access quickly your Todos dashboard by clicking the round gray icon +next to the search bar in the upper right corner. + + + +## What triggers a Todo + +A Todo appears in your Todos dashboard when: + +- an issue or merge request is assigned to you +- you are `@mentioned` in an issue or merge request, be it the description of + the issue/merge request or in a comment + +>**Note:** Commenting on a commit will _not_ trigger a Todo. + +## How a Todo is marked as Done + +Any action to the corresponding issue or merge request will mark your Todo as +**Done**. This action can include: + +- changing the assignee +- changing the milestone +- adding/removing a label +- commenting on the issue + +In case where you think no action is needed, you can manually mark the todo as +done by clicking the corresponding **Done** button, and it will disappear from +your Todos list. If you want to mark all your Todos as done, just click on the +**Mark all as done** button. + +--- + +In order for a Todo to be marked as done, the action must be coming from you. +So, if you close the related issue or merge the merge request yourself, and you +had a Todo for that, it will automatically get marked as done. On the other +hand, if someone else closes, merges or takes action on the issue or merge +request, your Todo will remain pending. This makes sense because you may need +to give attention to an issue even if it has been resolved. + +There is just one Todo per issue or merge request, so mentioning a user a +hundred times in an issue will only trigger one Todo. + +## Filtering your Todos + +In general, there are four kinds of filters you can use on your Todos +dashboard: + +| Filter | Description | +| ------ | ----------- | +| Project | Filter by project | +| Author | Filter by the author that triggered the Todo | +| Type | Filter by issue or merge request | +| Action | Filter by the action that triggered the Todo (Assigned or Mentioned)| + +You can choose more than one filters at the same time. + +[ce-2817]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2817 diff --git a/doc/user/workflow/web_editor.md b/doc/user/workflow/web_editor.md new file mode 100644 index 00000000000..1832567a34c --- /dev/null +++ b/doc/user/workflow/web_editor.md @@ -0,0 +1,152 @@ +# GitLab Web Editor + +Sometimes it's easier to make quick changes directly from the GitLab interface +than to clone the project and use the Git command line tool. In this feature +highlight we look at how you can create a new file, directory, branch or +tag from the file browser. All of these actions are available from a single +dropdown menu. + +## Create a file + +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New file** from the dropdown. + + + +--- + +Enter a file name in the **File name** box. Then, add file content in the editor +area. Add a descriptive commit message and choose a branch. The branch field +will default to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox will appear allowing you to start a new merge +request after you commit the changes. + +When you are satisfied with your new file, click **Commit Changes** at the bottom. + + + +## Upload a file + +The ability to create a file is great when the content is text. However, this +doesn't work well for binary data such as images, PDFs or other file types. In +this case you need to upload a file. + +From a project's files page, click the '+' button to the right of the branch +selector. Choose **Upload file** from the dropdown. + + + +--- + +Once the upload dialog pops up there are two ways to upload your file. Either +drag and drop a file on the pop up or use the **click to upload** link. A file +preview will appear once you have selected a file to upload. + +Enter a commit message, choose a branch, and click **Upload file** when you are +ready. + + + +## Create a directory + +To keep files in the repository organized it is often helpful to create a new +directory. + +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New directory** from the dropdown. + + + +--- + +In the new directory dialog enter a directory name, a commit message and choose +the target branch. Click **Create directory** to finish. + + + +## Create a new branch + +There are multiple ways to create a branch from GitLab's web interface. + +### Create a new branch from an issue + +>**Note:** +This feature was [introduced][ce-2808] in GitLab 8.6. + +In case your development workflow dictates to have an issue for every merge +request, you can quickly create a branch right on the issue page which will be +tied with the issue itself. You can see a **New Branch** button after the issue +description, unless there is already a branch with the same name or a referenced +merge request. + + + +Once you click it, a new branch will be created that diverges from the default +branch of your project, by default `master`. The branch name will be based on +the title of the issue and as suffix it will have its ID. Thus, the example +screenshot above will yield a branch named +`2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`. + +After the branch is created, you can edit files in the repository to fix +the issue. When a merge request is created based on the newly created branch, +the description field will automatically display the [issue closing pattern] +`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +merge request is merged. + +### Create a new branch from a project's dashboard + +If you want to make changes to several files before creating a new merge +request, you can create a new branch up front. From a project's files page, +choose **New branch** from the dropdown. + + + +--- + +Enter a new **Branch name**. Optionally, change the **Create from** field +to choose which branch, tag or commit SHA this new branch will originate from. +This field will autocomplete if you start typing an existing branch or tag. +Click **Create branch** and you will be returned to the file browser on this new +branch. + + + +--- + +You can now make changes to any files, as needed. When you're ready to merge +the changes back to master you can use the widget at the top of the screen. +This widget only appears for a period of time after you create the branch or +modify files. + + + +## Create a new tag + +Tags are useful for marking major milestones such as production releases, +release candidates, and more. You can create a tag from a branch or a commit +SHA. From a project's files page, choose **New tag** from the dropdown. + + + +--- + +Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you +would like to create this new tag. You can optionally add a message and +release notes. The release notes section supports markdown format and you can +also upload an attachment. Click **Create tag** and you will be taken to the tag +list page. + + + +## Tips + +When creating or uploading a new file, or creating a new directory, you can +trigger a new merge request rather than committing directly to master. Enter +a new branch name in the **Target branch** field. You will notice a checkbox +appear that is labeled **Start a new merge request with these changes**. After +you commit the changes you will be taken to a new merge request form. + + + +[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 +[issue closing pattern]: ../customization/issue_closing.md diff --git a/doc/user/workflow/wip_merge_requests.md b/doc/user/workflow/wip_merge_requests.md new file mode 100644 index 00000000000..46035a5e6b6 --- /dev/null +++ b/doc/user/workflow/wip_merge_requests.md @@ -0,0 +1,13 @@ +# "Work In Progress" Merge Requests + +To prevent merge requests from accidentally being accepted before they're completely ready, GitLab blocks the "Accept" button for merge requests that have been marked a **Work In Progress**. + + + +To mark a merge request a Work In Progress, simply start its title with `[WIP]` or `WIP:`. + + + +To allow a Work In Progress merge request to be accepted again when it's ready, simply remove the `WIP` prefix. + + diff --git a/doc/user/workflow/wip_merge_requests/blocked_accept_button.png b/doc/user/workflow/wip_merge_requests/blocked_accept_button.png Binary files differnew file mode 100644 index 00000000000..4791e5de972 --- /dev/null +++ b/doc/user/workflow/wip_merge_requests/blocked_accept_button.png diff --git a/doc/user/workflow/wip_merge_requests/mark_as_wip.png b/doc/user/workflow/wip_merge_requests/mark_as_wip.png Binary files differnew file mode 100644 index 00000000000..8fa83a201ac --- /dev/null +++ b/doc/user/workflow/wip_merge_requests/mark_as_wip.png diff --git a/doc/user/workflow/wip_merge_requests/unmark_as_wip.png b/doc/user/workflow/wip_merge_requests/unmark_as_wip.png Binary files differnew file mode 100644 index 00000000000..d45e68f31c5 --- /dev/null +++ b/doc/user/workflow/wip_merge_requests/unmark_as_wip.png diff --git a/doc/user/workflow/workflow.md b/doc/user/workflow/workflow.md new file mode 100644 index 00000000000..f70e41df842 --- /dev/null +++ b/doc/user/workflow/workflow.md @@ -0,0 +1,31 @@ +# Feature branch workflow + +1. Clone project: + + ```bash + git clone git@example.com:project-name.git + ``` + +1. Create branch with your feature: + + ```bash + git checkout -b $feature_name + ``` + +1. Write code. Commit changes: + + ```bash + git commit -am "My feature is ready" + ``` + +1. Push your branch to GitLab: + + ```bash + git push origin $feature_name + ``` + +1. Review your code on commits page. + +1. Create a merge request. + +1. Your team lead will review the code & merge it to the main branch. |
