|
| 1 | +# Git Config |
| 2 | + |
| 3 | +The WebKit project outlines a simplified recommended setup. This section outlines in greater detail other configuration options certain contributors may prefer. |
| 4 | + |
| 5 | +## Remotes |
| 6 | + |
| 7 | +### Alternate Remotes |
| 8 | + |
| 9 | +The WebKit project currently has 5 different remotes: |
| 10 | + |
| 11 | +- [github.com/WebKit/WebKit](https://github.com/WebKit/WebKit) |
| 12 | +- [svn.webkit.org](https://svn.webkit.org/repository/webkit/) |
| 13 | +- [git.webkit.org (https)](https://git.webkit.org/?p=WebKit.git;a=summary) |
| 14 | +- [git.webkit.org (http)](https://git.webkit.org/?p=WebKit.git;a=summary) |
| 15 | +- [github.com/WebKit/WebKit-http](https://github.com/WebKit/WebKit-http) |
| 16 | + |
| 17 | +The first remote, [github.com/WebKit/WebKit](https://github.com/WebKit/WebKit), is an actively maintained `git` mirror of [svn.webkit.org](https://svn.webkit.org/repository/webkit/) that will soon become the canonical home of the WebKit project. We strongly recommend that all contributors use this remote for routine development. |
| 18 | + |
| 19 | +The second remote, [svn.webkit.org](https://svn.webkit.org/repository/webkit/), is the current canonical remote for the WebKit project. If a contributor is contributing to the WebKit project on a release branch, this is the remote they should be using. Note that this remote is Subversion, not git. |
| 20 | + |
| 21 | +[git.webkit.org (https)](https://git.webkit.org/?p=WebKit.git;a=summary) is a deprecated `git` mirror of [svn.webkit.org](https://svn.webkit.org/repository/webkit/). This mirror is maintained, but commit authorship is incorrect. This means that the shas of commits in this repository _do not_ match those from [github.com/WebKit/WebKit](https://github.com/WebKit/WebKit). This remote is sufficient for patch workflows, but contributors relying on it should migrate to [github.com/WebKit/WebKit](https://github.com/WebKit/WebKit) as we start using pull requests. |
| 22 | + |
| 23 | +[git.webkit.org (http)](https://git.webkit.org/?p=WebKit.git;a=summary) and [github.com/WebKit/WebKit-http](https://github.com/WebKit/WebKit-http) the same repository but served in different locations. This remote is no longer maintained and should not be relied on. |
| 24 | + |
| 25 | +### Forking |
| 26 | + |
| 27 | +Since `git` is a decentralized version control system, a local copy can work with any remote that has the same set of shas. GitHub pull requests take advantage of this. After running [`git-webkit setup`](/WebKit/WebKit/wiki/Contributing#setup), the `.git/config` in the local WebKit repository should look something like this: |
| 28 | + |
| 29 | +``` |
| 30 | +[remote "origin"] |
| 31 | + url = https://github.com/WebKit/WebKit.git |
| 32 | + fetch = +refs/heads/*:refs/remotes/origin/* |
| 33 | +[remote "<username>"] |
| 34 | + url = https://github.com/<username>/WebKit.git |
| 35 | + fetch = +refs/heads/*:refs/remotes/<username>/* |
| 36 | +[remote "fork"] |
| 37 | + url = https://github.com/<username>/WebKit.git |
| 38 | + fetch = +refs/heads/*:refs/remotes/fork/* |
| 39 | +``` |
| 40 | + |
| 41 | +Now, if a contributor runs `git push fork eng/some-branch`, `eng/some-branch` will be pushed to the remote `fork`, which should correspond to that contributor's personal fork of the WebKit project on GitHub. Likewise, running `git checkout remotes/fork/eng/some-branch` will checkout `eng/some-branch` according to that contributor's `fork` remote. |
| 42 | + |
| 43 | +[`git-webkit setup`](/WebKit/WebKit/wiki/Contributing#setup) also configures a remote with a contributors GitHub username. This is because if other contributors would like to checkout code from a pull request which they do not own, contributors will need to add this: |
| 44 | + |
| 45 | +``` |
| 46 | +[remote "<username>"] |
| 47 | + url = https://github.com/<username>/WebKit.git |
| 48 | + fetch = +refs/heads/*:refs/remotes/<username>/* |
| 49 | +``` |
| 50 | + |
| 51 | +to their `.git/config` and run `git checkout remotes/<username>/eng/some-branch`. This is what `git-webkit checkout pr-#` and EWS machines do to retrieve a contributor's change. |
| 52 | + |
| 53 | +## Configuration Options |
| 54 | + |
| 55 | +[`git-webkit setup`](/WebKit/WebKit/wiki/Contributing#setup) automatically sets or prompts the contributor to define a number of `git` configuration options. Most contributors should use the defaults recommended by [`git-webkit setup`](/WebKit/WebKit/wiki/Contributing#setup). This section defines, in detail, what an option does and why the WebKit project recommends a certain setting. |
| 56 | + |
| 57 | +### user.email |
| 58 | + |
| 59 | +Prompts: |
| 60 | +``` |
| 61 | +Set '<email>' as the git user email for this repository |
| 62 | +Enter git user email for this repository: |
| 63 | +``` |
| 64 | + |
| 65 | +The `user.email` option is usually configured globally, and will become the contact information in `git` when authoring or committing a change. This is also the part of a commit that GitHub uses when attributing commits to specific users. The email a contributor defines here should be one of that contributor's emails in GitHub so that changes are correctly attributed to the contributor. |
| 66 | + |
| 67 | +The WebKit project asks contributors to define this value for their WebKit repository specifically because a contributor's reported email may change over time, and may even differ between machines. [`git-webkit setup`'s](/WebKit/WebKit/wiki/Contributing#setup) prompt is an effort to make contributors think about what their reported contact information for this specific checkout should be. |
| 68 | + |
| 69 | +Note that the author and committer listed in a `git` commit can easily be spoofed, so `user.email` plays no part in authentication. It is strictly for communication to other contributors. |
| 70 | + |
| 71 | +### user.name |
| 72 | + |
| 73 | +Prompts: |
| 74 | +``` |
| 75 | +Set '<name>' as the git user name for this repository |
| 76 | +Enter git user name for this repository: |
| 77 | +``` |
| 78 | + |
| 79 | +The `user.name` option is usually configured globally, and will become the listed name in `git` when authoring or committing a change. The name a contributor defines here should be one that individual expects other contributors to use when interacting with them. |
| 80 | + |
| 81 | +Note that the author and committer listed in a `git` commit can easily be spoofed, so `user.name` plays no part in authentication. It is strictly for communication to other contributors. |
| 82 | + |
| 83 | +### pull.rebase |
| 84 | + |
| 85 | +When a contributor is updating a branch from a remote, a local branch may have commits that do not exist on the remote. This usually happens when a contributor is committing local changes. `git` supports "rebasing" and "merging" in these cases. |
| 86 | + |
| 87 | +"rebasing" means updating the local branch reference to match the remote and then re-applying local commits on top of the tip of the updated branch. For changes which are small relative to the size of the repository, this is the cleanest method of applying local changes to an updated branch. |
| 88 | + |
| 89 | +"merging" means creating a new "merge commit" which has both the most recent commit from the newly updated remote and the most recent local commit as its parents. This technique is useful if the number and magnitude of local commits are large relative to the size of the repository. Note that many project explicitly ban pushing merge commits because they can make bisection and reasoning about continuous integration difficult. |
| 90 | + |
| 91 | +The `pull.rebase` configuration will automatically use a `rebase` workflow when running `git pull`. The WebKit project strongly recommends a `rebase` workflow and does not allow merge commits on `main` and other protected branches. |
| 92 | + |
| 93 | +### color.status/color.diff/color.branch |
| 94 | + |
| 95 | +Prompts: |
| 96 | +``` |
| 97 | +Auto-color status, diff, and branch for this repository? |
| 98 | +``` |
| 99 | + |
| 100 | +Applies coloring to various `git` commands, most notably `git log` and `git diff`. A number of `git-webkit` commands also use this configuration setting when deciding when to display color. Most users will want to use `auto`, although contributors who are colorblind may wish to either customize these colors or disable them completely. |
| 101 | + |
| 102 | +### diff.* |
| 103 | + |
| 104 | +`diff` options will apply to different file types and modify the output of `git diff` to be more human-readable. |
| 105 | + |
| 106 | +### core.editor |
| 107 | + |
| 108 | +Prompts: |
| 109 | +``` |
| 110 | +Pick a commit message editor for this repository: |
| 111 | + 1) [default] |
| 112 | + 2) Sublime |
| 113 | + 3) vi |
| 114 | + 4) open |
| 115 | +``` |
| 116 | + |
| 117 | +When creating or editing commit messages, `git` will invoke an external editor. By default on most systems, this is `vi`. The `core.editor` option lets a user of `git` change what editor they would like to use globally or within a repository. Note that the invocation of the editor should block until the user closes the editor. |
| 118 | + |
| 119 | +### merge.* |
| 120 | + |
| 121 | +`git` does basic automatic conflict resolution, but certain types of files may be difficult to resolve with what `git` provides. Specifying a `merge.driver` for a category of files can help automatically resolve conflicts in these files when running `git` commands, most notable, `git pull`. This is most common with frequently changing versioning files or ChangeLogs. |
| 122 | + |
| 123 | +### svn-remote |
| 124 | + |
| 125 | +This configuration options pairs a local branch in a contributor's checkout to a subversion branch on a specified remote. This configuration is required to use `git svn` commands. Note that `git-webkit find` allows a pure `git` checkout to reason about Subversion revisions without specifying an `svn-remote` for the branch containing the revision in question. |
| 126 | + |
| 127 | +## WebKit Options |
| 128 | + |
| 129 | +[`git-webkit`] respects a few options that are specific to the `webkitscmpy` library. [`git-webkit setup`](/WebKit/WebKit/wiki/Contributing#setup) does automatically configure some of these, [`metadata/project_config`](/WebKit/WebKit/blob/main/metadata/project_config) also contains a few default values for the project. |
| 130 | + |
| 131 | +### webkitscmpy.pull-request |
| 132 | + |
| 133 | +When responding to review feedback, contributors can either append commits to their original changes or force push and overwrite existing commits. `git-webkit pull-request` supports both workflows, and the `webkitscmpy.pull-request` option can be set to either `overwrite` or `append` to control which workflow `git-webkit` assumes a contributor is using. |
| 134 | + |
| 135 | +### webkitscmpy.history |
| 136 | + |
| 137 | +Prompts: |
| 138 | +``` |
| 139 | +Would you like to create new branches to retain history when you overwrite |
| 140 | +a pull request branch? |
| 141 | + 1) [when-user-owned] |
| 142 | + 2) disabled |
| 143 | + 3) always |
| 144 | + 4) never |
| 145 | +``` |
| 146 | + |
| 147 | +Managing pull requests often involves force pushing. This may result in historical changes being lost as a contributor responds to feedback. `git-webkit` supports saving old branches for the duration of a pull request. Some projects may wish to aggressively disable this option with `never` because contributors do not own user-specific forks. `when-user-owned` is generally considered the default option, which will create history branches only when a contributor owns a remote fork and is using the `overwrite` workflow. |
| 148 | + |
0 commit comments