721 lines
45 KiB
HTML
721 lines
45 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Using Git - Rust Compiler Development Guide</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="A guide to developing the Rust compiler (rustc)">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "";
|
|
const default_light_theme = "light";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Rust Compiler Development Guide</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/git.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="using-git"><a class="header" href="#using-git">Using Git</a></h1>
|
|
<ul>
|
|
<li><a href="#prerequisites">Prerequisites</a></li>
|
|
<li><a href="#standard-process">Standard Process</a></li>
|
|
<li><a href="#troubleshooting-git-issues">Troubleshooting git issues</a>
|
|
<ul>
|
|
<li><a href="#i-made-a-merge-commit-by-accident">I made a merge commit by accident.</a></li>
|
|
<li><a href="#i-deleted-my-fork-on-github">I deleted my fork on GitHub!</a></li>
|
|
<li><a href="#i-changed-a-submodule-by-accident">I changed a submodule by accident</a></li>
|
|
<li><a href="#i-see-error-cannot-rebase-when-i-try-to-rebase">I see "error: cannot rebase" when I try to rebase</a></li>
|
|
<li><a href="#i-see-untracked-files-srcstdarch">I see 'Untracked Files: src/stdarch'?</a></li>
|
|
<li><a href="#i-see--head">I see <code><<< HEAD</code>?</a></li>
|
|
<li><a href="#failed-to-push-some-refs">failed to push some refs</a></li>
|
|
<li><a href="#git-is-trying-to-rebase-commits-i-didnt-write">Git is trying to rebase commits I didn't write?</a></li>
|
|
<li><a href="#quick-note-about-submodules">Quick note about submodules</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#rebasing-and-conflicts">Rebasing and Conflicts</a>
|
|
<ul>
|
|
<li><a href="#rebasing">Rebasing</a></li>
|
|
<li><a href="#keeping-things-up-to-date">Keeping things up to date</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#advanced-rebasing">Advanced Rebasing</a>
|
|
<ul>
|
|
<li><a href="#squash-your-commits">Squash your commits</a></li>
|
|
<li><a href="#git-range-diff"><code>git range-diff</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#no-merge-policy">No-Merge Policy</a></li>
|
|
<li><a href="#tips-for-reviewing">Tips for reviewing</a>
|
|
<ul>
|
|
<li><a href="#hiding-whitespace">Hiding whitespace</a></li>
|
|
<li><a href="#fetching-prs">Fetching PRs</a></li>
|
|
<li><a href="#moving-large-sections-of-code">Moving large sections of code</a></li>
|
|
<li><a href="#range-diff">range-diff</a></li>
|
|
<li><a href="#ignoring-changes-to-specific-files">Ignoring changes to specific files</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#git-submodules">Git submodules</a>
|
|
<ul>
|
|
<li><a href="#hard-resetting-submodules">Hard-resetting submodules</a></li>
|
|
<li><a href="#deinit-git-submodules">Deinit git submodules</a></li>
|
|
<li><a href="#overcoming-fatal-not-a-git-repository-submodulegitmodulessubmodule">Overcoming <code>fatal: not a git repository: <submodule>/../../.git/modules/<submodule></code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#ignoring-commits-during-git-blame">Ignoring commits during <code>git blame</code></a></li>
|
|
</ul>
|
|
<p>The Rust project uses <a href="https://git-scm.com">Git</a> to manage its source code. In order to
|
|
contribute, you'll need some familiarity with its features so that your changes
|
|
can be incorporated into the compiler.</p>
|
|
<p>The goal of this page is to cover some of the more common questions and
|
|
problems new contributors face. Although some Git basics will be covered here,
|
|
if you find that this is still a little too fast for you, it might make sense
|
|
to first read some introductions to Git, such as the Beginner and Getting
|
|
started sections of <a href="https://www.atlassian.com/git/tutorials/what-is-version-control">this tutorial from Atlassian</a>. GitHub also
|
|
provides <a href="https://docs.github.com/en/get-started/quickstart/set-up-git">documentation</a> and <a href="https://guides.github.com/introduction/git-handbook/">guides</a> for beginners, or you can consult the
|
|
more in depth <a href="https://git-scm.com/book/en/v2/">book from Git</a>.</p>
|
|
<p>This guide is incomplete. If you run into trouble with git that this page doesn't help with,
|
|
please <a href="https://github.com/rust-lang/rustc-dev-guide/issues/new">open an issue</a> so we can document how to fix it.</p>
|
|
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
|
|
<p>We'll assume that you've installed Git, forked <a href="https://github.com/rust-lang/rust">rust-lang/rust</a>, and cloned the
|
|
forked repo to your PC. We'll use the command line interface to interact
|
|
with Git; there are also a number of GUIs and IDE integrations that can
|
|
generally do the same things.</p>
|
|
<p>If you've cloned your fork, then you will be able to reference it with <code>origin</code>
|
|
in your local repo. It may be helpful to also set up a remote for the official
|
|
rust-lang/rust repo via</p>
|
|
<pre><code class="language-console">git remote add upstream https://github.com/rust-lang/rust.git
|
|
</code></pre>
|
|
<p>if you're using HTTPS, or</p>
|
|
<pre><code class="language-console">git remote add upstream git@github.com:rust-lang/rust.git
|
|
</code></pre>
|
|
<p>if you're using SSH.</p>
|
|
<p><strong>NOTE:</strong> This page is dedicated to workflows for <code>rust-lang/rust</code>, but will likely be
|
|
useful when contributing to other repositories in the Rust project.</p>
|
|
<h2 id="standard-process"><a class="header" href="#standard-process">Standard Process</a></h2>
|
|
<p>Below is the normal procedure that you're likely to use for most minor changes
|
|
and PRs:</p>
|
|
<ol>
|
|
<li>Ensure that you're making your changes on top of master:
|
|
<code>git checkout master</code>.</li>
|
|
<li>Get the latest changes from the Rust repo: <code>git pull upstream master --ff-only</code>.
|
|
(see <a href="#keeping-things-up-to-date">No-Merge Policy</a> for more info about this).</li>
|
|
<li>Make a new branch for your change: <code>git checkout -b issue-12345-fix</code>.</li>
|
|
<li>Make some changes to the repo and test them.</li>
|
|
<li>Stage your changes via <code>git add src/changed/file.rs src/another/change.rs</code>
|
|
and then commit them with <code>git commit</code>. Of course, making intermediate commits
|
|
may be a good idea as well. Avoid <code>git add .</code>, as it makes it too easy to
|
|
unintentionally commit changes that should not be committed, such as submodule
|
|
updates. You can use <code>git status</code> to check if there are any files you forgot
|
|
to stage.</li>
|
|
<li>Push your changes to your fork: <code>git push --set-upstream origin issue-12345-fix</code>
|
|
(After adding commits, you can use <code>git push</code> and after rebasing or
|
|
pulling-and-rebasing, you can use <code>git push --force-with-lease</code>).</li>
|
|
<li><a href="https://guides.github.com/activities/forking/#making-a-pull-request">Open a PR</a> from your fork to <code>rust-lang/rust</code>'s master branch.</li>
|
|
</ol>
|
|
<p>If you end up needing to rebase and are hitting conflicts, see <a href="#rebasing">Rebasing</a>.
|
|
If you want to track upstream while working on long-running feature/issue, see
|
|
<a href="#keeping-things-up-to-date">Keeping things up to date</a>.</p>
|
|
<p>If your reviewer requests changes, the procedure for those changes looks much
|
|
the same, with some steps skipped:</p>
|
|
<ol>
|
|
<li>Ensure that you're making changes to the most recent version of your code:
|
|
<code>git checkout issue-12345-fix</code>.</li>
|
|
<li>Make, stage, and commit your additional changes just like before.</li>
|
|
<li>Push those changes to your fork: <code>git push</code>.</li>
|
|
</ol>
|
|
<h2 id="troubleshooting-git-issues"><a class="header" href="#troubleshooting-git-issues">Troubleshooting git issues</a></h2>
|
|
<p>You don't need to clone <code>rust-lang/rust</code> from scratch if it's out of date!
|
|
Even if you think you've messed it up beyond repair, there are ways to fix
|
|
the git state that don't require downloading the whole repository again.
|
|
Here are some common issues you might run into:</p>
|
|
<h3 id="i-made-a-merge-commit-by-accident"><a class="header" href="#i-made-a-merge-commit-by-accident">I made a merge commit by accident.</a></h3>
|
|
<p>Git has two ways to update your branch with the newest changes: merging and rebasing.
|
|
Rust <a href="#keeping-things-up-to-date">uses rebasing</a>. If you make a merge commit, it's not too hard to fix:
|
|
<code>git rebase -i upstream/master</code>.</p>
|
|
<p>See <a href="#rebasing">Rebasing</a> for more about rebasing.</p>
|
|
<h3 id="i-deleted-my-fork-on-github"><a class="header" href="#i-deleted-my-fork-on-github">I deleted my fork on GitHub!</a></h3>
|
|
<p>This is not a problem from git's perspective. If you run <code>git remote -v</code>,
|
|
it will say something like this:</p>
|
|
<pre><code class="language-console">$ git remote -v
|
|
origin git@github.com:jyn514/rust.git (fetch)
|
|
origin git@github.com:jyn514/rust.git (push)
|
|
upstream https://github.com/rust-lang/rust (fetch)
|
|
upstream https://github.com/rust-lang/rust (fetch)
|
|
</code></pre>
|
|
<p>If you renamed your fork, you can change the URL like this:</p>
|
|
<pre><code class="language-console">git remote set-url origin <URL>
|
|
</code></pre>
|
|
<p>where the <code><URL></code> is your new fork.</p>
|
|
<h3 id="i-changed-a-submodule-by-accident"><a class="header" href="#i-changed-a-submodule-by-accident">I changed a submodule by accident</a></h3>
|
|
<p>Usually people notice this when rustbot posts a comment on github that <code>cargo</code> has been modified:</p>
|
|
<p><img src="./img/rustbot-submodules.png" alt="rustbot submodule comment" /></p>
|
|
<p>You might also notice conflicts in the web UI:</p>
|
|
<p><img src="./img/submodule-conflicts.png" alt="conflict in src/tools/cargo" /></p>
|
|
<p>The most common cause is that you rebased after a change and ran <code>git add .</code> without first running
|
|
<code>x</code> to update the submodules. Alternatively, you might have run <code>cargo fmt</code> instead of <code>x fmt</code>
|
|
and modified files in a submodule, then committed the changes.</p>
|
|
<p>To fix it, do the following things (if you changed a submodule other than cargo,
|
|
replace <code>src/tools/cargo</code> with the path to that submodule):</p>
|
|
<ol>
|
|
<li>See which commit has the accidental changes: <code>git log --stat -n1 src/tools/cargo</code></li>
|
|
<li>Revert the changes to that commit: <code>git checkout <my-commit>~ src/tools/cargo</code>. Type <code>~</code>
|
|
literally but replace <code><my-commit></code> with the output from step 1.</li>
|
|
<li>Tell git to commit the changes: <code>git commit --fixup <my-commit></code></li>
|
|
<li>Repeat steps 1-3 for all the submodules you modified.
|
|
<ul>
|
|
<li>If you modified the submodule in several different commits, you will need to repeat steps 1-3
|
|
for each commit you modified. You'll know when to stop when the <code>git log</code> command shows a commit
|
|
that's not authored by you.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Squash your changes into the existing commits: <code>git rebase --autosquash -i upstream/master</code></li>
|
|
<li><a href="#standard-process">Push your changes</a>.</li>
|
|
</ol>
|
|
<h3 id="i-see-error-cannot-rebase-when-i-try-to-rebase"><a class="header" href="#i-see-error-cannot-rebase-when-i-try-to-rebase">I see "error: cannot rebase" when I try to rebase</a></h3>
|
|
<p>These are two common errors to see when rebasing:</p>
|
|
<pre><code class="language-console">error: cannot rebase: Your index contains uncommitted changes.
|
|
error: Please commit or stash them.
|
|
</code></pre>
|
|
<pre><code class="language-console">error: cannot rebase: You have unstaged changes.
|
|
error: Please commit or stash them.
|
|
</code></pre>
|
|
<p>(See <a href="https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states">https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states</a> for the difference between the two.)</p>
|
|
<p>This means you have made changes since the last time you made a commit. To be able to rebase, either
|
|
commit your changes, or make a temporary commit called a "stash" to have them still not be committed
|
|
when you finish rebasing. You may want to configure git to make this "stash" automatically, which
|
|
will prevent the "cannot rebase" error in nearly all cases:</p>
|
|
<pre><code class="language-console">git config --global rebase.autostash true
|
|
</code></pre>
|
|
<p>See <a href="https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning">https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning</a> for more info about stashing.</p>
|
|
<h3 id="i-see-untracked-files-srcstdarch"><a class="header" href="#i-see-untracked-files-srcstdarch">I see 'Untracked Files: src/stdarch'?</a></h3>
|
|
<p>This is left over from the move to the <code>library/</code> directory.
|
|
Unfortunately, <code>git rebase</code> does not follow renames for submodules, so you
|
|
have to delete the directory yourself:</p>
|
|
<pre><code class="language-console">rm -r src/stdarch
|
|
</code></pre>
|
|
<h3 id="i-see--head"><a class="header" href="#i-see--head">I see <code><<< HEAD</code>?</a></h3>
|
|
<p>You were probably in the middle of a rebase or merge conflict. See
|
|
<a href="#rebasing-and-conflicts">Conflicts</a> for how to fix the conflict. If you don't care about the changes
|
|
and just want to get a clean copy of the repository back, you can use <code>git reset</code>:</p>
|
|
<pre><code class="language-console"># WARNING: this throws out any local changes you've made! Consider resolving the conflicts instead.
|
|
git reset --hard master
|
|
</code></pre>
|
|
<h3 id="failed-to-push-some-refs"><a class="header" href="#failed-to-push-some-refs">failed to push some refs</a></h3>
|
|
<p><code>git push</code> will not work properly and say something like this:</p>
|
|
<pre><code class="language-console"> ! [rejected] issue-xxxxx -> issue-xxxxx (non-fast-forward)
|
|
error: failed to push some refs to 'https://github.com/username/rust.git'
|
|
hint: Updates were rejected because the tip of your current branch is behind
|
|
hint: its remote counterpart. Integrate the remote changes (e.g.
|
|
hint: 'git pull ...') before pushing again.
|
|
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
|
|
</code></pre>
|
|
<p>The advice this gives is incorrect! Because of Rust's
|
|
<a href="#no-merge-policy">"no-merge" policy</a> the merge commit created by <code>git pull</code>
|
|
will not be allowed in the final PR, in addition to defeating the point of the
|
|
rebase! Use <code>git push --force-with-lease</code> instead.</p>
|
|
<h3 id="git-is-trying-to-rebase-commits-i-didnt-write"><a class="header" href="#git-is-trying-to-rebase-commits-i-didnt-write">Git is trying to rebase commits I didn't write?</a></h3>
|
|
<p>If you see many commits in your rebase list, or merge commits, or commits by other people that you
|
|
didn't write, it likely means you're trying to rebase over the wrong branch. For example, you may
|
|
have a <code>rust-lang/rust</code> remote <code>upstream</code>, but ran <code>git rebase origin/master</code> instead of <code>git rebase upstream/master</code>. The fix is to abort the rebase and use the correct branch instead:</p>
|
|
<pre><code class="language-console">git rebase --abort
|
|
git rebase -i upstream/master
|
|
</code></pre>
|
|
<details><summary>Click here to see an example of rebasing over the wrong branch</summary>
|
|
<p><img src="img/other-peoples-commits.png" alt="Interactive rebase over the wrong branch" /></p>
|
|
</details>
|
|
<h3 id="quick-note-about-submodules"><a class="header" href="#quick-note-about-submodules">Quick note about submodules</a></h3>
|
|
<p>When updating your local repository with <code>git pull</code>, you may notice that sometimes
|
|
Git says you have modified some files that you have never edited. For example,
|
|
running <code>git status</code> gives you something like (note the <code>new commits</code> mention):</p>
|
|
<pre><code class="language-console">On branch master
|
|
Your branch is up to date with 'origin/master'.
|
|
|
|
Changes not staged for commit:
|
|
(use "git add <file>..." to update what will be committed)
|
|
(use "git restore <file>..." to discard changes in working directory)
|
|
modified: src/llvm-project (new commits)
|
|
modified: src/tools/cargo (new commits)
|
|
|
|
no changes added to commit (use "git add" and/or "git commit -a")
|
|
</code></pre>
|
|
<p>These changes are not changes to files: they are changes to submodules (more on this <a href="#git-submodules">later</a>).
|
|
To get rid of those:</p>
|
|
<pre><code class="language-console">git submodule update
|
|
</code></pre>
|
|
<p>Some submodules are not actually needed; for example, <code>src/llvm-project</code> doesn't need to be checked
|
|
out if you're using <code>download-ci-llvm</code>. To avoid having to keep fetching its history, you can use
|
|
<code>git submodule deinit -f src/llvm-project</code>, which will also avoid it showing as modified again.</p>
|
|
<h2 id="rebasing-and-conflicts"><a class="header" href="#rebasing-and-conflicts">Rebasing and Conflicts</a></h2>
|
|
<p>When you edit your code locally, you are making changes to the version of
|
|
rust-lang/rust that existed when you created your feature branch. As such, when
|
|
you submit your PR it is possible that some of the changes that have been made
|
|
to rust-lang/rust since then are in conflict with the changes you've made.
|
|
When this happens, you need to resolve the conflicts before your changes can be
|
|
merged. To do that, you need to rebase your work on top of rust-lang/rust.</p>
|
|
<h3 id="rebasing"><a class="header" href="#rebasing">Rebasing</a></h3>
|
|
<p>To rebase your feature branch on top of the newest version of the master branch
|
|
of rust-lang/rust, checkout your branch, and then run this command:</p>
|
|
<pre><code class="language-console">git pull --rebase https://github.com/rust-lang/rust.git master
|
|
</code></pre>
|
|
<blockquote>
|
|
<p>If you are met with the following error:</p>
|
|
<pre><code class="language-console">error: cannot pull with rebase: Your index contains uncommitted changes.
|
|
error: please commit or stash them.
|
|
</code></pre>
|
|
<p>it means that you have some uncommitted work in your working tree. In that
|
|
case, run <code>git stash</code> before rebasing, and then <code>git stash pop</code> after you
|
|
have rebased and fixed all conflicts.</p>
|
|
</blockquote>
|
|
<p>When you rebase a branch on master, all the changes on your branch are
|
|
reapplied to the most recent version of master. In other words, Git tries to
|
|
pretend that the changes you made to the old version of master were instead
|
|
made to the new version of master. During this process, you should expect to
|
|
encounter at least one "rebase conflict." This happens when Git's attempt to
|
|
reapply the changes fails because your changes conflicted with other changes
|
|
that have been made. You can tell that this happened because you'll see
|
|
lines in the output that look like</p>
|
|
<pre><code class="language-console">CONFLICT (content): Merge conflict in file.rs
|
|
</code></pre>
|
|
<p>When you open these files, you'll see sections of the form</p>
|
|
<pre><code class="language-console"><<<<<<< HEAD
|
|
Original code
|
|
=======
|
|
Your code
|
|
>>>>>>> 8fbf656... Commit fixes 12345
|
|
</code></pre>
|
|
<p>This represents the lines in the file that Git could not figure out how to
|
|
rebase. The section between <code><<<<<<< HEAD</code> and <code>=======</code> has the code from
|
|
master, while the other side has your version of the code. You'll need to
|
|
decide how to deal with the conflict. You may want to keep your changes,
|
|
keep the changes on master, or combine the two.</p>
|
|
<p>Generally, resolving the conflict consists of two steps: First, fix the
|
|
particular conflict. Edit the file to make the changes you want and remove the
|
|
<code><<<<<<<</code>, <code>=======</code> and <code>>>>>>>></code> lines in the process. Second, check the
|
|
surrounding code. If there was a conflict, its likely there are some logical
|
|
errors lying around too! It's a good idea to run <code>x check</code> here to make sure
|
|
there are no glaring errors.</p>
|
|
<p>Once you're all done fixing the conflicts, you need to stage the files that had
|
|
conflicts in them via <code>git add</code>. Afterwards, run <code>git rebase --continue</code> to let
|
|
Git know that you've resolved the conflicts and it should finish the rebase.</p>
|
|
<p>Once the rebase has succeeded, you'll want to update the associated branch on
|
|
your fork with <code>git push --force-with-lease</code>.</p>
|
|
<h3 id="keeping-things-up-to-date"><a class="header" href="#keeping-things-up-to-date">Keeping things up to date</a></h3>
|
|
<p>The above section on <a href="#rebasing">Rebasing</a> is a specific
|
|
guide on rebasing work and dealing with merge conflicts.
|
|
Here is some general advice about how to keep your local repo
|
|
up-to-date with upstream changes:</p>
|
|
<p>Using <code>git pull upstream master</code> while on your local master branch regularly
|
|
will keep it up-to-date. You will also want to rebase your feature branches
|
|
up-to-date as well. After pulling, you can checkout the feature branches
|
|
and rebase them:</p>
|
|
<pre><code class="language-console">git checkout master
|
|
git pull upstream master --ff-only # to make certain there are no merge commits
|
|
git rebase master feature_branch
|
|
git push --force-with-lease # (set origin to be the same as local)
|
|
</code></pre>
|
|
<p>To avoid merges as per the <a href="#no-merge-policy">No-Merge Policy</a>, you may want to use
|
|
<code>git config pull.ff only</code> (this will apply the config only to the local repo)
|
|
to ensure that Git doesn't create merge commits when <code>git pull</code>ing, without
|
|
needing to pass <code>--ff-only</code> or <code>--rebase</code> every time.</p>
|
|
<p>You can also <code>git push --force-with-lease</code> from master to double-check that your
|
|
feature branches are in sync with their state on the Github side.</p>
|
|
<h2 id="advanced-rebasing"><a class="header" href="#advanced-rebasing">Advanced Rebasing</a></h2>
|
|
<h3 id="squash-your-commits"><a class="header" href="#squash-your-commits">Squash your commits</a></h3>
|
|
<p>"Squashing" commits into each other causes them to be merged into a single
|
|
commit. Both the upside and downside of this is that it simplifies the history.
|
|
On the one hand, you lose track of the steps in which changes were made, but
|
|
the history becomes easier to work with.</p>
|
|
<p>If there are no conflicts and you are just squashing to clean up the history,
|
|
use <code>git rebase --interactive --keep-base master</code>. This keeps the fork point
|
|
of your PR the same, making it easier to review the diff of what happened
|
|
across your rebases.</p>
|
|
<p>Squashing can also be useful as part of conflict resolution.
|
|
If your branch contains multiple consecutive rewrites of the same code, or if
|
|
the rebase conflicts are extremely severe, you can use
|
|
<code>git rebase --interactive master</code> to gain more control over the process. This
|
|
allows you to choose to skip commits, edit the commits that you do not skip,
|
|
change the order in which they are applied, or "squash" them into each other.</p>
|
|
<p>Alternatively, you can sacrifice the commit history like this:</p>
|
|
<pre><code class="language-console"># squash all the changes into one commit so you only have to worry about conflicts once
|
|
git rebase -i --keep-base master # and squash all changes along the way
|
|
git rebase master
|
|
# fix all merge conflicts
|
|
git rebase --continue
|
|
</code></pre>
|
|
<p>You also may want to squash just the last few commits together, possibly
|
|
because they only represent "fixups" and not real changes. For example,
|
|
<code>git rebase --interactive HEAD~2</code> will allow you to edit the two commits only.</p>
|
|
<h3 id="git-range-diff"><a class="header" href="#git-range-diff"><code>git range-diff</code></a></h3>
|
|
<p>After completing a rebase, and before pushing up your changes, you may want to
|
|
review the changes between your old branch and your new one. You can do that
|
|
with <code>git range-diff master @{upstream} HEAD</code>.</p>
|
|
<p>The first argument to <code>range-diff</code>, <code>master</code> in this case, is the base revision
|
|
that you're comparing your old and new branch against. The second argument is
|
|
the old version of your branch; in this case, <code>@upstream</code> means the version that
|
|
you've pushed to GitHub, which is the same as what people will see in your pull
|
|
request. Finally, the third argument to <code>range-diff</code> is the <em>new</em> version of
|
|
your branch; in this case, it is <code>HEAD</code>, which is the commit that is currently
|
|
checked-out in your local repo.</p>
|
|
<p>Note that you can also use the equivalent, abbreviated form <code>git range-diff master @{u} HEAD</code>.</p>
|
|
<p>Unlike in regular Git diffs, you'll see a <code>-</code> or <code>+</code> next to another <code>-</code> or <code>+</code>
|
|
in the range-diff output. The marker on the left indicates a change between the
|
|
old branch and the new branch, and the marker on the right indicates a change
|
|
you've committed. So, you can think of a range-diff as a "diff of diffs" since
|
|
it shows you the differences between your old diff and your new diff.</p>
|
|
<p>Here's an example of <code>git range-diff</code> output (taken from <a href="https://git-scm.com/docs/git-range-diff#_examples">Git's
|
|
docs</a>):</p>
|
|
<pre><code class="language-console">-: ------- > 1: 0ddba11 Prepare for the inevitable!
|
|
1: c0debee = 2: cab005e Add a helpful message at the start
|
|
2: f00dbal ! 3: decafe1 Describe a bug
|
|
@@ -1,3 +1,3 @@
|
|
Author: A U Thor <author@example.com>
|
|
|
|
-TODO: Describe a bug
|
|
+Describe a bug
|
|
@@ -324,5 +324,6
|
|
This is expected.
|
|
|
|
-+What is unexpected is that it will also crash.
|
|
++Unexpectedly, it also crashes. This is a bug, and the jury is
|
|
++still out there how to fix it best. See ticket #314 for details.
|
|
|
|
Contact
|
|
3: bedead < -: ------- TO-UNDO
|
|
</code></pre>
|
|
<p>(Note that <code>git range-diff</code> output in your terminal will probably be easier to
|
|
read than in this example because it will have colors.)</p>
|
|
<p>Another feature of <code>git range-diff</code> is that, unlike <code>git diff</code>, it will also
|
|
diff commit messages. This feature can be useful when amending several commit
|
|
messages so you can make sure you changed the right parts.</p>
|
|
<p><code>git range-diff</code> is a very useful command, but note that it can take some time
|
|
to get used to its output format. You may also find Git's documentation on the
|
|
command useful, especially their <a href="https://git-scm.com/docs/git-range-diff#_examples">"Examples" section</a>.</p>
|
|
<h2 id="no-merge-policy"><a class="header" href="#no-merge-policy">No-Merge Policy</a></h2>
|
|
<p>The rust-lang/rust repo uses what is known as a "rebase workflow." This means
|
|
that merge commits in PRs are not accepted. As a result, if you are running
|
|
<code>git merge</code> locally, chances are good that you should be rebasing instead. Of
|
|
course, this is not always true; if your merge will just be a fast-forward,
|
|
like the merges that <code>git pull</code> usually performs, then no merge commit is
|
|
created and you have nothing to worry about. Running <code>git config merge.ff only</code>
|
|
(this will apply the config to the local repo)
|
|
once will ensure that all the merges you perform are of this type, so that you
|
|
cannot make a mistake.</p>
|
|
<p>There are a number of reasons for this decision and like all others, it is a
|
|
tradeoff. The main advantage is the generally linear commit history. This
|
|
greatly simplifies bisecting and makes the history and commit log much easier
|
|
to follow and understand.</p>
|
|
<h2 id="tips-for-reviewing"><a class="header" href="#tips-for-reviewing">Tips for reviewing</a></h2>
|
|
<p><strong>NOTE</strong>: This section is for <em>reviewing</em> PRs, not authoring them.</p>
|
|
<h3 id="hiding-whitespace"><a class="header" href="#hiding-whitespace">Hiding whitespace</a></h3>
|
|
<p>Github has a button for disabling whitespace changes that may be useful.
|
|
You can also use <code>git diff -w origin/master</code> to view changes locally.</p>
|
|
<p><img src="./img/github-whitespace-changes.png" alt="hide whitespace" /></p>
|
|
<h3 id="fetching-prs"><a class="header" href="#fetching-prs">Fetching PRs</a></h3>
|
|
<p>To checkout PRs locally, you can use <code>git fetch upstream pull/NNNNN/head && git checkout FETCH_HEAD</code>.</p>
|
|
<p>You can also use github's cli tool. Github shows a button on PRs where you can copy-paste the
|
|
command to check it out locally. See <a href="https://cli.github.com/">https://cli.github.com/</a> for more info.</p>
|
|
<p><img src="./img/github-cli.png" alt="gh suggestion" /></p>
|
|
<h3 id="moving-large-sections-of-code"><a class="header" href="#moving-large-sections-of-code">Moving large sections of code</a></h3>
|
|
<p>Git and Github's default diff view for large moves <em>within</em> a file is quite poor; it will show each
|
|
line as deleted and each line as added, forcing you to compare each line yourself. Git has an option
|
|
to show moved lines in a different color:</p>
|
|
<pre><code class="language-console">git log -p --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change
|
|
</code></pre>
|
|
<p>See <a href="https://git-scm.com/docs/git-diff#Documentation/git-diff.txt---color-movedltmodegt">the docs for <code>--color-moved</code></a> for more info.</p>
|
|
<h3 id="range-diff"><a class="header" href="#range-diff">range-diff</a></h3>
|
|
<p>See <a href="#git-range-diff">the relevant section for PR authors</a>. This can be useful for comparing code
|
|
that was force-pushed to make sure there are no unexpected changes.</p>
|
|
<h3 id="ignoring-changes-to-specific-files"><a class="header" href="#ignoring-changes-to-specific-files">Ignoring changes to specific files</a></h3>
|
|
<p>Many large files in the repo are autogenerated. To view a diff that ignores changes to those files,
|
|
you can use the following syntax (e.g. Cargo.lock):</p>
|
|
<pre><code class="language-console">git log -p ':!Cargo.lock'
|
|
</code></pre>
|
|
<p>Arbitrary patterns are supported (e.g. <code>:!compiler/*</code>). Patterns use the same syntax as
|
|
<code>.gitignore</code>, with <code>:</code> prepended to indicate a pattern.</p>
|
|
<h2 id="git-submodules"><a class="header" href="#git-submodules">Git submodules</a></h2>
|
|
<p><strong>NOTE</strong>: submodules are a nice thing to know about, but it <em>isn't</em> an absolute
|
|
prerequisite to contribute to <code>rustc</code>. If you are using Git for the first time,
|
|
you might want to get used to the main concepts of Git before reading this section.</p>
|
|
<p>The <code>rust-lang/rust</code> repository uses <a href="https://git-scm.com/book/en/v2/Git-Tools-Submodules">Git submodules</a> as a way to use other
|
|
Rust projects from within the <code>rust</code> repo. Examples include Rust's fork of
|
|
<code>llvm-project</code>, <code>cargo</code> and libraries like <code>stdarch</code> and <code>backtrace</code>.</p>
|
|
<p>Those projects are developed and maintained in an separate Git (and GitHub)
|
|
repository, and they have their own Git history/commits, issue tracker and PRs.
|
|
Submodules allow us to create some sort of embedded sub-repository inside the
|
|
<code>rust</code> repository and use them like they were directories in the <code>rust</code> repository.</p>
|
|
<p>Take <code>llvm-project</code> for example. <code>llvm-project</code> is maintained in the <a href="https://github.com/rust-lang/llvm-project"><code>rust-lang/llvm-project</code></a>
|
|
repository, but it is used in <code>rust-lang/rust</code> by the compiler for code generation and
|
|
optimization. We bring it in <code>rust</code> as a submodule, in the <code>src/llvm-project</code> folder.</p>
|
|
<p>The contents of submodules are ignored by Git: submodules are in some sense isolated
|
|
from the rest of the repository. However, if you try to <code>cd src/llvm-project</code> and then
|
|
run <code>git status</code>:</p>
|
|
<pre><code class="language-console">HEAD detached at 9567f08afc943
|
|
nothing to commit, working tree clean
|
|
</code></pre>
|
|
<p>As far as git is concerned, you are no longer in the <code>rust</code> repo, but in the <code>llvm-project</code> repo.
|
|
You will notice that we are in "detached HEAD" state, i.e. not on a branch but on a
|
|
particular commit.</p>
|
|
<p>This is because, like any dependency, we want to be able to control which version to use.
|
|
Submodules allow us to do just that: every submodule is "pinned" to a certain
|
|
commit, which doesn't change unless modified manually. If you use <code>git checkout <commit></code>
|
|
in the <code>llvm-project</code> directory and go back to the <code>rust</code> directory, you can stage this
|
|
change like any other, e.g. by running <code>git add src/llvm-project</code>. (Note that if
|
|
you <em>don't</em> stage the change to commit, then you run the risk that running
|
|
<code>x</code> will just undo your change by switching back to the previous commit when
|
|
it automatically "updates" the submodules.)</p>
|
|
<p>This version selection is usually done by the maintainers of the project, and
|
|
looks like <a href="https://github.com/rust-lang/rust/pull/99464/files">this</a>.</p>
|
|
<p>Git submodules take some time to get used to, so don't worry if it isn't perfectly
|
|
clear yet. You will rarely have to use them directly and, again, you don't need
|
|
to know everything about submodules to contribute to Rust. Just know that they
|
|
exist and that they correspond to some sort of embedded subrepository dependency
|
|
that Git can nicely and fairly conveniently handle for us.</p>
|
|
<h3 id="hard-resetting-submodules"><a class="header" href="#hard-resetting-submodules">Hard-resetting submodules</a></h3>
|
|
<p>Sometimes you might run into (when you run <code>git status</code>)</p>
|
|
<pre><code class="language-console">Changes not staged for commit:
|
|
(use "git add <file>..." to update what will be committed)
|
|
(use "git restore <file>..." to discard changes in working directory)
|
|
(commit or discard the untracked or modified content in submodules)
|
|
modified: src/llvm-project (new commits, modified content)
|
|
</code></pre>
|
|
<p>and when you try to run <code>git submodule update</code> it breaks horribly with errors like</p>
|
|
<pre><code class="language-console">error: RPC failed; curl 92 HTTP/2 stream 7 was not closed cleanly: CANCEL (err 8)
|
|
error: 2782 bytes of body are still expected
|
|
fetch-pack: unexpected disconnect while reading sideband packet
|
|
fatal: early EOF
|
|
fatal: fetch-pack: invalid index-pack output
|
|
fatal: Fetched in submodule path 'src/llvm-project', but it did not contain 5a5152f653959d14d68613a3a8a033fb65eec021. Direct fetching of that commit failed.
|
|
</code></pre>
|
|
<p>If you see <code>(new commits, modified content)</code> you can run</p>
|
|
<pre><code class="language-console">git submodule foreach git reset --hard
|
|
</code></pre>
|
|
<p>and then try <code>git submodule update</code> again.</p>
|
|
<h3 id="deinit-git-submodules"><a class="header" href="#deinit-git-submodules">Deinit git submodules</a></h3>
|
|
<p>If that doesn't work, you can try to deinit all git submodules...</p>
|
|
<pre><code class="language-console">git submodule deinit -f --all
|
|
</code></pre>
|
|
<p>Unfortunately sometimes your local git submodules configuration can become
|
|
completely messed up for some reason.</p>
|
|
<h3 id="overcoming-fatal-not-a-git-repository-submodulegitmodulessubmodule"><a class="header" href="#overcoming-fatal-not-a-git-repository-submodulegitmodulessubmodule">Overcoming <code>fatal: not a git repository: <submodule>/../../.git/modules/<submodule></code></a></h3>
|
|
<p>Sometimes, for some forsaken reason, you might run into</p>
|
|
<pre><code class="language-console">fatal: not a git repository: src/gcc/../../.git/modules/src/gcc
|
|
</code></pre>
|
|
<p>In this situation, for the given submodule path, i.e. <code><submodule_path> = src/gcc</code> in this example, you need to:</p>
|
|
<ol>
|
|
<li><code>rm -rf <submodule_path>/.git</code></li>
|
|
<li><code>rm -rf .git/modules/<submodule_path>/config</code></li>
|
|
<li><code>rm -rf .gitconfig.lock</code> if somehow the <code>.gitconfig</code> lock is orphaned.</li>
|
|
</ol>
|
|
<p>Then do something like <code>./x fmt</code> to have bootstrap manage the submodule
|
|
checkouts for you.</p>
|
|
<h2 id="ignoring-commits-during-git-blame"><a class="header" href="#ignoring-commits-during-git-blame">Ignoring commits during <code>git blame</code></a></h2>
|
|
<p>Some commits contain large reformatting changes that don't otherwise change functionality. They can
|
|
be instructed to be ignored by <code>git blame</code> through
|
|
<a href="https://github.com/rust-lang/rust/blob/master/.git-blame-ignore-revs"><code>.git-blame-ignore-revs</code></a>:</p>
|
|
<ol>
|
|
<li>Configure <code>git blame</code> to use <code>.git-blame-ignore-revs</code> as the list of commits to ignore: <code>git config blame.ignorerevsfile .git-blame-ignore-revs</code></li>
|
|
<li>Add suitable commits that you wish to be ignored by <code>git blame</code>.</li>
|
|
</ol>
|
|
<p>Please include a comment for the commit that you add to <code>.git-blame-ignore-revs</code> so people can
|
|
easily figure out <em>why</em> a commit is ignored.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="compiler-team.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="rustbot.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="compiler-team.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="rustbot.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="elasticlunr.min.js"></script>
|
|
<script src="mark.min.js"></script>
|
|
<script src="searcher.js"></script>
|
|
|
|
<script src="clipboard.min.js"></script>
|
|
<script src="highlight.js"></script>
|
|
<script src="book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
<script src="mermaid.min.js"></script>
|
|
<script src="mermaid-init.js"></script>
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|