| = Gerrit Code Review - Project Configuration |
| |
| [[project-creation]] |
| == Project Creation |
| |
| There are several ways to create a new project in Gerrit: |
| |
| - in the Web UI under 'Projects' > 'Create Project' |
| - via the link:rest-api-projects.html#create-project[Create Project] |
| REST endpoint |
| - via the link:cmd-create-project.html[create-project] SSH command |
| |
| To be able to create new projects the global capability |
| link:access-control.html#capability_createProject[Create Project] must |
| be granted. |
| |
| In addition, projects can be created link:#manual_project_creation[ |
| manually]. |
| |
| [[manual_project_creation]] |
| === Manual Project Creation |
| |
| . Create a Git repository under `gerrit.basePath`: |
| + |
| ==== |
| git --git-dir=$base_path/new/project.git init |
| ==== |
| + |
| [TIP] |
| By tradition the repository directory name should have a `.git` |
| suffix. |
| + |
| To also make this repository available over the anonymous git:// |
| protocol, don't forget to create a `git-daemon-export-ok` file: |
| + |
| ==== |
| touch $base_path/new/project.git/git-daemon-export-ok |
| ==== |
| |
| . Register Project |
| + |
| Either restart the server, or flush the `project_list` cache: |
| + |
| ==== |
| ssh -p 29418 localhost gerrit flush-caches --cache project_list |
| ==== |
| |
| [[project_options]] |
| == Project Options |
| |
| [[submit_type]] |
| === Submit Type |
| |
| The method Gerrit uses to submit a change to a project can be |
| modified by any project owner through the project console, `Projects` > |
| `List` > my/project. The following methods are supported: |
| |
| [[fast_forward_only]] |
| * Fast Forward Only |
| + |
| With this method no merge commits are produced. All merges must |
| be handled on the client, prior to uploading to Gerrit for review. |
| + |
| To submit a change, the change must be a strict superset of the |
| destination branch. That is, the change must already contain the |
| tip of the destination branch at submit time. |
| |
| [[merge_if_necessary]] |
| * Merge If Necessary |
| + |
| This is the default for a new project. |
| + |
| If the change being submitted is a strict superset of the destination |
| branch, then the branch is fast-forwarded to the change. If not, |
| then a merge commit is automatically created. This is identical |
| to the classical `git merge` behavior, or `git merge --ff`. |
| |
| [[always_merge]] |
| * Always Merge |
| + |
| Always produce a merge commit, even if the change is a strict |
| superset of the destination branch. This is identical to the |
| behavior of `git merge --no-ff`, and may be useful if the |
| project needs to follow submits with `git log --first-parent`. |
| |
| [[cherry_pick]] |
| * Cherry Pick |
| + |
| Always cherry pick the patch set, ignoring the parent lineage |
| and instead creating a brand new commit on top of the current |
| branch head. |
| + |
| When cherry picking a change, Gerrit automatically appends onto the |
| end of the commit message a short summary of the change's approvals, |
| and a URL link back to the change on the web. The committer header |
| is also set to the submitter, while the author header retains the |
| original patch set author. |
| + |
| Note that Gerrit ignores patch set dependencies when operating in |
| cherry-pick mode. Submitters must remember to submit changes in |
| the right order since inter-change dependencies will not be |
| enforced for them. |
| |
| [[rebase_if_necessary]] |
| * Rebase If Necessary |
| + |
| If the change being submitted is a strict superset of the destination |
| branch, then the branch is fast-forwarded to the change. If not, |
| then the change is automatically rebased and then the branch is |
| fast-forwarded to the change. |
| |
| When Gerrit tries to do a merge, by default the merge will only |
| succeed if there is no path conflict. A path conflict occurs when |
| the same file has also been changed on the other side of the merge. |
| |
| [[content_merge]] |
| If `Allow content merges` is enabled, Gerrit will try |
| to do a content merge when a path conflict occurs. |
| |
| [[project-state]] |
| === State |
| |
| This setting defines the state of the project. A project can have the |
| following states: |
| |
| - `Active`: |
| + |
| The project is active and users can see and modify the project according |
| to their access rights on the project. |
| |
| - `Read Only`: |
| + |
| The project is read only and all modifying operations on it are |
| disabled. E.g. this means that pushing to this project fails for all |
| users even if they have push permissions assigned on it. |
| + |
| Setting a project to this state is an easy way to temporary close a |
| project, as you can keep all write access rights in place and they will |
| become active again as soon as the project state is set back to |
| `Active`. |
| + |
| This state also makes sense if a project was moved to another location. |
| In this case all new development should happen in the new project and |
| you want to prevent that somebody accidentally works on the old |
| project, while keeping the old project around for old references. |
| |
| - `Hidden`: |
| + |
| The project is hidden and only visible to project owners. Other users |
| are not able to see the project even if they have read permissions |
| granted on the project. |
| |
| === Use target branch when determining new changes to open |
| |
| The `create-new-change-for-all-not-in-target` option provides a |
| convenience for selecting link:user-upload.html#base[the merge base] |
| by setting it automatically to the target branch's tip so you can |
| create new changes for all commits not in the target branch. |
| |
| This option is disabled if the tip of the push is a merge commit. |
| |
| This option also only works if there are no merge commits in the |
| commit chain, in such cases it fails warning the user that such |
| pushes can only be performed by manually specifying |
| link:user-upload.html#base[bases] |
| |
| This option is useful if you want to push a change to your personal |
| branch first and for review to another branch for example. Or in cases |
| where a commit is already merged into a branch and you want to create |
| a new open change for that commit on another branch. |
| |
| [[require-change-id]] |
| === Require Change-Id |
| |
| The `Require Change-Id in commit message` option defines whether a |
| link:user-changeid.html[Change-Id] in the commit message is required |
| for pushing a commit for review. If this option is set, trying to push |
| a commit for review that doesn't contain a Change-Id in the commit |
| message fails with link:error-missing-changeid.html[missing Change-Id |
| in commit message footer]. |
| |
| It is recommended to set this option and use a |
| link:user-changeid.html#create[commit-msg hook] (or other client side |
| tooling like EGit) to automatically generate Change-Id's for new |
| commits. This way the Change-Id is automatically in place when changes |
| are reworked or rebased and uploading new patch sets gets easy. |
| |
| If this option is not set, commits can be uploaded without a Change-Id, |
| but then users have to remember to copy the assigned Change-Id from the |
| change screen and insert it manually into the commit message when they |
| want to upload a second patch set. |
| |
| === Maximum Git Object Size Limit |
| |
| This option defines the maximum allowed Git object size that |
| receive-pack will accept. If an object is larger than the given size |
| the pack-parsing will abort and the push operation will fail. |
| |
| With this option users can be prevented from uploading commits that |
| contain files which are too large. |
| |
| Normally the link:config-gerrit.html#receive.maxObjectSizeLimit[maximum |
| Git object size limit] is configured globally for a Gerrit server. At |
| the project level, the maximum Git object size limit can be further |
| reduced, but not extended. The displayed effective limit shows the |
| maximum Git object size limit that is actually used on the project. |
| |
| The defined maximum Git object size limit is inherited by any child |
| project. |
| |
| === Require Signed-off-by |
| |
| The `Require Signed-off-by in commit message` option defines whether a |
| link:user-signedoffby.html[Signed-off-by] line in the commit message is |
| required for pushing a commit. If this option is set, trying to push a |
| commit that doesn't contain a Signed-off-by line in the commit message |
| fails with link:error-not-signed-off-by.html[not Signed-off-by |
| author/committer/uploader in commit message footer]. |
| |
| [[branch-admin]] |
| == Branch Administration |
| |
| [[branch-creation]] |
| === Branch Creation |
| |
| There are several ways to create a new branch in a project: |
| |
| - in the Web UI under 'Projects' > 'List' > <project> > 'Branches' |
| - via the link:rest-api-projects.html#create-branch[Create Branch] |
| REST endpoint |
| - via the link:cmd-create-branch.html[create-branch] SSH command |
| - by using a git client to push a commit to a non-existing branch |
| |
| To be able to create new branches the user must have the |
| link:access-control.html#category_create[Create Reference] access |
| right. In addition, project owners and Gerrit administrators can create |
| new branches from the Web UI or via REST even without having the |
| `Create Reference` access right. |
| |
| When using the Web UI, the REST endpoint or the SSH command it is only |
| possible to create branches on commits that already exist in the |
| repository. |
| |
| If a branch name does not start with `refs/` it is automatically |
| prefixed with `refs/heads/`. |
| |
| The starting revision for a new branch can be any valid SHA-1 |
| expression, as long as it resolves to a commit. Abbreviated SHA-1s |
| are not supported. |
| |
| [[branch-deletion]] |
| === Branch Deletion |
| |
| There are several ways to delete a branch: |
| |
| - in the Web UI under 'Projects' > 'List' > <project> > 'Branches' |
| - via the link:rest-api-projects.html#delete-branch[Delete Branch] |
| REST endpoint |
| - by using a git client to force push nothing to an existing branch |
| + |
| ==== |
| $ git push --force origin :refs/heads/<branch-to-delete> |
| ==== |
| |
| To be able to delete branches, the user must have the |
| link:access-control.html#category_push[Push] access right with the |
| `force` option. In addition, project owners and Gerrit administrators |
| can delete branches from the Web UI or via REST even without having the |
| `Force Push` access right. |
| |
| [[default-branch]] |
| === Default Branch |
| |
| The default branch of a remote repository is defined by its `HEAD`. |
| For convenience reasons, when the repository is cloned Git creates a |
| local branch for this default branch and checks it out. |
| |
| Project owners can set `HEAD` |
| |
| - in the Web UI under 'Projects' > 'List' > <project> > 'Branches' or |
| - via the link:rest-api-projects.html#set-head[Set HEAD] REST endpoint |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |