blob: 4d49873ef1a1eec96e1125db1436c264209b0513 [file] [log] [blame] [edit]
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Using Git - Guide to Rustc Development</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="A guide to developing 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" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var 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 type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item affix "><a href="about-this-guide.html">About this guide</a></li><li class="chapter-item affix "><a href="getting-started.html">Getting Started</a></li><li class="spacer"></li><li class="chapter-item affix "><li class="part-title">Building and debugging rustc</li><li class="chapter-item "><a href="building/how-to-build-and-run.html"><strong aria-hidden="true">1.</strong> How to Build and Run the Compiler</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="building/prerequisites.html"><strong aria-hidden="true">1.1.</strong> Prerequisites</a></li><li class="chapter-item "><a href="building/suggested.html"><strong aria-hidden="true">1.2.</strong> Suggested Workflows</a></li><li class="chapter-item "><a href="building/build-install-distribution-artifacts.html"><strong aria-hidden="true">1.3.</strong> Distribution artifacts</a></li><li class="chapter-item "><a href="building/compiler-documenting.html"><strong aria-hidden="true">1.4.</strong> Documenting Compiler</a></li><li class="chapter-item "><a href="rustdoc.html"><strong aria-hidden="true">1.5.</strong> Rustdoc overview</a></li><li class="chapter-item "><a href="building/new-target.html"><strong aria-hidden="true">1.6.</strong> Adding a new target</a></li></ol></li><li class="chapter-item "><a href="tests/intro.html"><strong aria-hidden="true">2.</strong> The compiler testing framework</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="tests/running.html"><strong aria-hidden="true">2.1.</strong> Running tests</a></li><li class="chapter-item "><a href="tests/adding.html"><strong aria-hidden="true">2.2.</strong> Adding new tests</a></li><li class="chapter-item "><a href="compiletest.html"><strong aria-hidden="true">2.3.</strong> Using compiletest commands to control test execution</a></li></ol></li><li class="chapter-item "><a href="compiler-debugging.html"><strong aria-hidden="true">3.</strong> Debugging the Compiler</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="tracing.html"><strong aria-hidden="true">3.1.</strong> Using the tracing/logging instrumentation</a></li></ol></li><li class="chapter-item "><a href="profiling.html"><strong aria-hidden="true">4.</strong> Profiling the compiler</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="profiling/with_perf.html"><strong aria-hidden="true">4.1.</strong> with the linux perf tool</a></li><li class="chapter-item "><a href="profiling/wpa_profiling.html"><strong aria-hidden="true">4.2.</strong> with Windows Performance Analyzer</a></li></ol></li><li class="chapter-item "><a href="crates-io.html"><strong aria-hidden="true">5.</strong> crates.io Dependencies</a></li><li class="chapter-item affix "><li class="part-title">Contributing to Rust</li><li class="chapter-item "><a href="contributing.html"><strong aria-hidden="true">6.</strong> Introduction</a></li><li class="chapter-item "><a href="compiler-team.html"><strong aria-hidden="true">7.</strong> About the compiler team</a></li><li class="chapter-item expanded "><a href="git.html" class="active"><strong aria-hidden="true">8.</strong> Using Git</a></li><li class="chapter-item "><a href="rustbot.html"><strong aria-hidden="true">9.</strong> Mastering @rustbot</a></li><li class="chapter-item "><a href="walkthrough.html"><strong aria-hidden="true">10.</strong> Walkthrough: a typical contribution</a></li><li class="chapter-item "><a href="bug-fix-procedure.html"><strong aria-hidden="true">11.</strong> Bug Fix Procedure</a></li><li class="chapter-item "><a href="implementing_new_features.html"><strong aria-hidden="true">12.</strong> Implementing new features</a></li><li class="chapter-item "><a href="stability.html"><strong aria-hidden="true">13.</strong> Stability attributes</a></li><li class="chapter-item "><a href="stabilization_guide.html"><strong aria-hidden="true">14.</strong> Stabilizing Features</a></li><li class="chapter-item "><a href="feature-gates.html"><strong aria-hidden="true">15.</strong> Feature Gates</a></li><li class="chapter-item "><a href="conventions.html"><strong aria-hidden="true">16.</strong> Coding conventions</a></li><li class="chapter-item "><a href="notification-groups/about.html"><strong aria-hidden="true">17.</strong> Notification groups</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="notification-groups/arm.html"><strong aria-hidden="true">17.1.</strong> ARM</a></li><li class="chapter-item "><a href="notification-groups/cleanup-crew.html"><strong aria-hidden="true">17.2.</strong> Cleanup Crew</a></li><li class="chapter-item "><a href="notification-groups/llvm.html"><strong aria-hidden="true">17.3.</strong> LLVM</a></li><li class="chapter-item "><a href="notification-groups/risc-v.html"><strong aria-hidden="true">17.4.</strong> RISC-V</a></li><li class="chapter-item "><a href="notification-groups/windows.html"><strong aria-hidden="true">17.5.</strong> Windows</a></li></ol></li><li class="chapter-item "><a href="licenses.html"><strong aria-hidden="true">18.</strong> Licenses</a></li><li class="chapter-item affix "><li class="part-title">High-level Compiler Architecture</li><li class="chapter-item "><a href="part-2-intro.html"><strong aria-hidden="true">19.</strong> Prologue</a></li><li class="chapter-item "><a href="overview.html"><strong aria-hidden="true">20.</strong> Overview of the Compiler</a></li><li class="chapter-item "><a href="compiler-src.html"><strong aria-hidden="true">21.</strong> The compiler source code</a></li><li class="chapter-item "><a href="building/bootstrapping.html"><strong aria-hidden="true">22.</strong> Bootstrapping</a></li><li class="chapter-item "><a href="query.html"><strong aria-hidden="true">23.</strong> Queries: demand-driven compilation</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="queries/query-evaluation-model-in-detail.html"><strong aria-hidden="true">23.1.</strong> The Query Evaluation Model in Detail</a></li><li class="chapter-item "><a href="queries/incremental-compilation.html"><strong aria-hidden="true">23.2.</strong> Incremental compilation</a></li><li class="chapter-item "><a href="queries/incremental-compilation-in-detail.html"><strong aria-hidden="true">23.3.</strong> Incremental compilation In Detail</a></li><li class="chapter-item "><a href="incrcomp-debugging.html"><strong aria-hidden="true">23.4.</strong> Debugging and Testing</a></li><li class="chapter-item "><a href="salsa.html"><strong aria-hidden="true">23.5.</strong> Salsa</a></li></ol></li><li class="chapter-item "><a href="memory.html"><strong aria-hidden="true">24.</strong> Memory Management in Rustc</a></li><li class="chapter-item "><a href="serialization.html"><strong aria-hidden="true">25.</strong> Serialization in Rustc</a></li><li class="chapter-item "><a href="parallel-rustc.html"><strong aria-hidden="true">26.</strong> Parallel Compilation</a></li><li class="chapter-item "><a href="rustdoc-internals.html"><strong aria-hidden="true">27.</strong> Rustdoc internals</a></li><li class="chapter-item affix "><li class="part-title">Source Code Representation</li><li class="chapter-item "><a href="part-3-intro.html"><strong aria-hidden="true">28.</strong> Prologue</a></li><li class="chapter-item "><a href="cli.html"><strong aria-hidden="true">29.</strong> Command-line arguments</a></li><li class="chapter-item "><a href="rustc-driver.html"><strong aria-hidden="true">30.</strong> The Rustc Driver and Interface</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="rustc-driver-interacting-with-the-ast.html"><strong aria-hidden="true">30.1.</strong> Ex: Type checking through rustc_interface</a></li><li class="chapter-item "><a href="rustc-driver-getting-diagnostics.html"><strong aria-hidden="true">30.2.</strong> Ex: Getting diagnostics through rustc_interface</a></li></ol></li><li class="chapter-item "><a href="syntax-intro.html"><strong aria-hidden="true">31.</strong> Syntax and the AST</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="the-parser.html"><strong aria-hidden="true">31.1.</strong> Lexing and Parsing</a></li><li class="chapter-item "><a href="macro-expansion.html"><strong aria-hidden="true">31.2.</strong> Macro expansion</a></li><li class="chapter-item "><a href="name-resolution.html"><strong aria-hidden="true">31.3.</strong> Name resolution</a></li><li class="chapter-item "><a href="test-implementation.html"><strong aria-hidden="true">31.4.</strong> #[test] Implementation</a></li><li class="chapter-item "><a href="panic-implementation.html"><strong aria-hidden="true">31.5.</strong> Panic Implementation</a></li><li class="chapter-item "><a href="ast-validation.html"><strong aria-hidden="true">31.6.</strong> AST Validation</a></li><li class="chapter-item "><a href="feature-gate-ck.html"><strong aria-hidden="true">31.7.</strong> Feature Gate Checking</a></li><li class="chapter-item "><a href="lang-items.html"><strong aria-hidden="true">31.8.</strong> Lang Items</a></li></ol></li><li class="chapter-item "><a href="hir.html"><strong aria-hidden="true">32.</strong> The HIR (High-level IR)</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="lowering.html"><strong aria-hidden="true">32.1.</strong> Lowering AST to HIR</a></li><li class="chapter-item "><a href="hir-debugging.html"><strong aria-hidden="true">32.2.</strong> Debugging</a></li></ol></li><li class="chapter-item "><a href="thir.html"><strong aria-hidden="true">33.</strong> The THIR (Typed High-level IR)</a></li><li class="chapter-item "><a href="mir/index.html"><strong aria-hidden="true">34.</strong> The MIR (Mid-level IR)</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="mir/construction.html"><strong aria-hidden="true">34.1.</strong> MIR construction</a></li><li class="chapter-item "><a href="mir/visitor.html"><strong aria-hidden="true">34.2.</strong> MIR visitor and traversal</a></li><li class="chapter-item "><a href="mir/passes.html"><strong aria-hidden="true">34.3.</strong> MIR passes: getting the MIR for a function</a></li></ol></li><li class="chapter-item "><a href="identifiers.html"><strong aria-hidden="true">35.</strong> Identifiers in the Compiler</a></li><li class="chapter-item "><a href="closure.html"><strong aria-hidden="true">36.</strong> Closure expansion</a></li><li class="chapter-item affix "><li class="part-title">Analysis</li><li class="chapter-item "><a href="part-4-intro.html"><strong aria-hidden="true">37.</strong> Prologue</a></li><li class="chapter-item "><a href="ty.html"><strong aria-hidden="true">38.</strong> The ty module: representing types</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="generics.html"><strong aria-hidden="true">38.1.</strong> Generics and substitutions</a></li><li class="chapter-item "><a href="ty-fold.html"><strong aria-hidden="true">38.2.</strong> TypeFolder and TypeFoldable</a></li><li class="chapter-item "><a href="generic_arguments.html"><strong aria-hidden="true">38.3.</strong> Generic arguments</a></li><li class="chapter-item "><a href="constants.html"><strong aria-hidden="true">38.4.</strong> Constants in the type system</a></li></ol></li><li class="chapter-item "><a href="type-inference.html"><strong aria-hidden="true">39.</strong> Type inference</a></li><li class="chapter-item "><a href="traits/resolution.html"><strong aria-hidden="true">40.</strong> Trait solving</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="early-late-bound.html"><strong aria-hidden="true">40.1.</strong> Early and Late Bound Parameters</a></li><li class="chapter-item "><a href="traits/hrtb.html"><strong aria-hidden="true">40.2.</strong> Higher-ranked trait bounds</a></li><li class="chapter-item "><a href="traits/caching.html"><strong aria-hidden="true">40.3.</strong> Caching subtleties</a></li><li class="chapter-item "><a href="traits/specialization.html"><strong aria-hidden="true">40.4.</strong> Specialization</a></li><li class="chapter-item "><a href="traits/chalk.html"><strong aria-hidden="true">40.5.</strong> Chalk-based trait solving</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="traits/lowering-to-logic.html"><strong aria-hidden="true">40.5.1.</strong> Lowering to logic</a></li><li class="chapter-item "><a href="traits/goals-and-clauses.html"><strong aria-hidden="true">40.5.2.</strong> Goals and clauses</a></li><li class="chapter-item "><a href="traits/canonical-queries.html"><strong aria-hidden="true">40.5.3.</strong> Canonical queries</a></li></ol></li></ol></li><li class="chapter-item "><a href="type-checking.html"><strong aria-hidden="true">41.</strong> Type checking</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="method-lookup.html"><strong aria-hidden="true">41.1.</strong> Method Lookup</a></li><li class="chapter-item "><a href="variance.html"><strong aria-hidden="true">41.2.</strong> Variance</a></li><li class="chapter-item "><a href="opaque-types-type-alias-impl-trait.html"><strong aria-hidden="true">41.3.</strong> Opaque Types</a></li></ol></li><li class="chapter-item "><a href="pat-exhaustive-checking.html"><strong aria-hidden="true">42.</strong> Pattern and Exhaustiveness Checking</a></li><li class="chapter-item "><a href="mir/dataflow.html"><strong aria-hidden="true">43.</strong> MIR dataflow</a></li><li class="chapter-item "><a href="borrow_check.html"><strong aria-hidden="true">44.</strong> The borrow checker</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="borrow_check/moves_and_initialization.html"><strong aria-hidden="true">44.1.</strong> Tracking moves and initialization</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="borrow_check/moves_and_initialization/move_paths.html"><strong aria-hidden="true">44.1.1.</strong> Move paths</a></li></ol></li><li class="chapter-item "><a href="borrow_check/type_check.html"><strong aria-hidden="true">44.2.</strong> MIR type checker</a></li><li class="chapter-item "><a href="borrow_check/region_inference.html"><strong aria-hidden="true">44.3.</strong> Region inference</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="borrow_check/region_inference/constraint_propagation.html"><strong aria-hidden="true">44.3.1.</strong> Constraint propagation</a></li><li class="chapter-item "><a href="borrow_check/region_inference/lifetime_parameters.html"><strong aria-hidden="true">44.3.2.</strong> Lifetime parameters</a></li><li class="chapter-item "><a href="borrow_check/region_inference/member_constraints.html"><strong aria-hidden="true">44.3.3.</strong> Member constraints</a></li><li class="chapter-item "><a href="borrow_check/region_inference/placeholders_and_universes.html"><strong aria-hidden="true">44.3.4.</strong> Placeholders and universes</a></li><li class="chapter-item "><a href="borrow_check/region_inference/closure_constraints.html"><strong aria-hidden="true">44.3.5.</strong> Closure constraints</a></li><li class="chapter-item "><a href="borrow_check/region_inference/error_reporting.html"><strong aria-hidden="true">44.3.6.</strong> Error reporting</a></li></ol></li><li class="chapter-item "><a href="borrow_check/two_phase_borrows.html"><strong aria-hidden="true">44.4.</strong> Two-phase-borrows</a></li></ol></li><li class="chapter-item "><a href="param_env.html"><strong aria-hidden="true">45.</strong> Parameter Environments</a></li><li class="chapter-item "><a href="diagnostics.html"><strong aria-hidden="true">46.</strong> Errors and Lints</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="diagnostics/sessiondiagnostic.html"><strong aria-hidden="true">46.1.</strong> Creating Errors With SessionDiagnostic</a></li><li class="chapter-item "><a href="diagnostics/lintstore.html"><strong aria-hidden="true">46.2.</strong> LintStore</a></li><li class="chapter-item "><a href="diagnostics/diagnostic-codes.html"><strong aria-hidden="true">46.3.</strong> Diagnostic Codes</a></li><li class="chapter-item "><a href="diagnostics/diagnostic-items.html"><strong aria-hidden="true">46.4.</strong> Diagnostic Items</a></li></ol></li><li class="chapter-item "><li class="part-title">MIR to Binaries</li><li class="chapter-item "><a href="part-5-intro.html"><strong aria-hidden="true">47.</strong> Prologue</a></li><li class="chapter-item "><a href="mir/optimizations.html"><strong aria-hidden="true">48.</strong> MIR optimizations</a></li><li class="chapter-item "><a href="mir/debugging.html"><strong aria-hidden="true">49.</strong> Debugging</a></li><li class="chapter-item "><a href="const-eval.html"><strong aria-hidden="true">50.</strong> Constant evaluation</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="miri.html"><strong aria-hidden="true">50.1.</strong> miri const evaluator</a></li></ol></li><li class="chapter-item "><a href="backend/monomorph.html"><strong aria-hidden="true">51.</strong> Monomorphization</a></li><li class="chapter-item "><a href="backend/lowering-mir.html"><strong aria-hidden="true">52.</strong> Lowering MIR</a></li><li class="chapter-item "><a href="backend/codegen.html"><strong aria-hidden="true">53.</strong> Code Generation</a><a class="toggle"><div></div></a></li><li><ol class="section"><li class="chapter-item "><a href="backend/updating-llvm.html"><strong aria-hidden="true">53.1.</strong> Updating LLVM</a></li><li class="chapter-item "><a href="backend/debugging.html"><strong aria-hidden="true">53.2.</strong> Debugging LLVM</a></li><li class="chapter-item "><a href="backend/backend-agnostic.html"><strong aria-hidden="true">53.3.</strong> Backend Agnostic Codegen</a></li><li class="chapter-item "><a href="backend/implicit-caller-location.html"><strong aria-hidden="true">53.4.</strong> Implicit Caller Location</a></li></ol></li><li class="chapter-item "><a href="backend/libs-and-metadata.html"><strong aria-hidden="true">54.</strong> Libraries and Metadata</a></li><li class="chapter-item "><a href="profile-guided-optimization.html"><strong aria-hidden="true">55.</strong> Profile-guided Optimization</a></li><li class="chapter-item "><a href="llvm-coverage-instrumentation.html"><strong aria-hidden="true">56.</strong> LLVM Source-Based Code Coverage</a></li><li class="chapter-item "><a href="sanitizers.html"><strong aria-hidden="true">57.</strong> Sanitizers Support</a></li><li class="chapter-item "><a href="debugging-support-in-rustc.html"><strong aria-hidden="true">58.</strong> Debugging Support in the Rust Compiler</a></li><li class="spacer"></li><li class="chapter-item affix "><a href="appendix/background.html">Appendix A: Background topics</a></li><li class="chapter-item affix "><a href="appendix/glossary.html">Appendix B: Glossary</a></li><li class="chapter-item affix "><a href="appendix/code-index.html">Appendix C: Code Index</a></li><li class="chapter-item affix "><a href="appendix/compiler-lecture.html">Appendix D: Compiler Lecture Series</a></li><li class="chapter-item affix "><a href="appendix/bibliography.html">Appendix E: Bibliography</a></li><li class="chapter-item affix "><a href="appendix/humorust.html">Appendix Z: HumorRust</a></li><li class="spacer"></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></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 bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<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="light">Light (default)</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">Guide to Rustc Development</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/tree/master/src/git.md?mode&#x3D;edit" 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 type="text/javascript">
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-deleted-my-fork-on-github">I deleted my fork on GitHub!</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>&lt;&lt;&lt; HEAD</code>?</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="#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="#git-submodules">Git submodules</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/github/getting-started-with-github/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>
<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-sh">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-sh">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-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>$ git remote -v
origin https://github.com//rust-lang/rust (fetch)
origin https://github.com//rust-lang/rust (push)
personal https://github.com/jyn514/rust (fetch)
personal https://github.com/jyn514/rust (push)
</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 personal &lt;URL&gt;
</code></pre>
<p>where the <code>&lt;URL&gt;</code> is your new fork.</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>&lt;&lt;&lt; HEAD</code>?</a></h3>
<p>You were probably in the middle of a rebase or merge conflict. See
<a href="#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="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>On branch master
Your branch is up to date with 'origin/master'.
Changes not staged for commit:
(use &quot;git add &lt;file&gt;...&quot; to update what will be committed)
(use &quot;git restore &lt;file&gt;...&quot; to discard changes in working directory)
modified: src/tools/cargo (new commits)
modified: src/tools/rls (new commits)
no changes added to commit (use &quot;git add&quot; and/or &quot;git commit -a&quot;)
</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, run <code>git submodule update</code>
(or run any <code>x.py</code> command, which will automatically update the submodules).
Note that there is (as of <!-- date: 2021-07 --> July 2021) a <a href="https://github.com/rust-lang/rust/issues/77620">bug</a> if you use
worktrees, submodules, and x.py in a commit hook. If you run into an error
like:</p>
<pre><code>error: failed to read `/home/joshua/rustc-worktree/src/tools/miri/cargo-miri/Cargo.toml`
Caused by:
No such file or directory (os error 2)
</code></pre>
<p>it's not anything you did wrong. There is a workaround in <a href="https://github.com/rust-lang/rust/issues/77620#issuecomment-705228229">the issue</a>.</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.</p>
<p>When this happens, you need to resolve the conflicts before your changes can be
merged. First, get a local copy of the conflicting changes: Checkout your local
master branch with <code>git checkout master</code>, then <code>git pull upstream master</code> to
update it with the most recent changes.</p>
<h3 id="rebasing"><a class="header" href="#rebasing">Rebasing</a></h3>
<p>You're now ready to start the rebasing process. Checkout the branch with your
changes and execute <code>git rebase master</code>.</p>
<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 &quot;rebase conflict.&quot; 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>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>&lt;&lt;&lt;&lt;&lt;&lt;&lt; HEAD
Original code
=======
Your code
&gt;&gt;&gt;&gt;&gt;&gt;&gt; 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>&lt;&lt;&lt;&lt;&lt;&lt;&lt; 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>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code>, <code>=======</code> and <code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</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.py 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>
<p>Note that <code>git push</code> will not work properly and say something like this:</p>
<pre><code> ! [rejected] issue-xxxxx -&gt; 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">&quot;no-merge&quot; 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="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>git checkout master
git pull upstream master --ff-only # to make certain there are no merge commits
git checkout feature_branch
git rebase master
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 keep your origin's master in sync with
upstream.</p>
<h2 id="advanced-rebasing"><a class="header" href="#advanced-rebasing">Advanced Rebasing</a></h2>
<p>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 &quot;squash&quot; them into each other.</p>
<p>Alternatively, you can sacrifice the commit history like this:</p>
<pre><code># squash all the changes into one commit so you only have to worry about conflicts once
git rebase -i $(git merge-base master HEAD) # and squash all changes along the way
git rebase master
# fix all merge conflicts
git rebase --continue
</code></pre>
<p>&quot;Squashing&quot; 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>You also may want to squash just the last few commits together, possibly
because they only represent &quot;fixups&quot; 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 &quot;diff of diffs&quot; 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>-: ------- &gt; 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 &lt;author@example.com&gt;
-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 &lt; -: ------- 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">&quot;Examples&quot; 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 &quot;rebase workflow.&quot; 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="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> and many devtools such as <code>cargo</code>, <code>rust-analyzer</code> and <code>rls</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>miri</code> for example. <code>miri</code> is maintained in the <a href="https://github.com/rust-lang/miri"><code>rust-lang/miri</code></a> repository,
but it is used in <code>rust-lang/rust</code> by the compiler for const evaluation. We bring it
in <code>rust</code> as a submodule, in the <code>src/tools/miri</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/tools/miri</code> and then
run <code>git status</code>:</p>
<pre><code>HEAD detached at 3fafb835
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>miri</code> repo.
You will notice that we are in &quot;detached HEAD&quot; 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 &quot;pinned&quot; to a certain
commit, which doesn't change unless modified manually. If you use <code>git checkout &lt;commit&gt;</code>
in the <code>miri</code> directory and go back to the <code>rust</code> directory, you can stage this
change like any other. This is usually done by the maintainers of the
project, and looks like <a href="https://github.com/rust-lang/rust/pull/77500/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>
</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" 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" 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 type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>