fd5b820d9c · matheusbsbs/matheus-bagliano

@@ -1,5 +1,4 @@

1 -Git User Manual

2 -===============

1 += Git User Manual

2

3 Git is a fast distributed revision control system.

4

@@ -41,12 +40,10 @@ complete.

40

41

42 [[repositories-and-branches]]

44 -Repositories and Branches

45 -=========================

43 +== Repositories and Branches

44

45 [[how-to-get-a-git-repository]]

48 -How to get a Git repository

49 ----------------------------

46 +=== How to get a Git repository

47

48 It will be useful to have a Git repository to experiment with as you

49 read this manual.

@@ -73,8 +70,7 @@ top-level directory named `.git`, which contains all the information

70 about the history of the project.

71

72 [[how-to-check-out]]

76 -How to check out a different version of a project

77 --------------------------------------------------

73 +=== How to check out a different version of a project

74

75 Git is best thought of as a tool for storing the history of a collection

76 of files. It stores the history as a compressed collection of

@@ -151,8 +147,7 @@ with no way to find the history it used to point to; so use this command

147 carefully.

148

149 [[understanding-commits]]

154 -Understanding History: Commits

155 -------------------------------

150 +=== Understanding History: Commits

151

152 Every change in the history of a project is represented by a commit.

153 The linkgit:git-show[1] command shows the most recent commit on the

@@ -202,8 +197,7 @@ history, including file data and directory contents, is stored in an object

197 with a name that is a hash of its contents.

198

199 [[understanding-reachability]]

205 -Understanding history: commits, parents, and reachability

206 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

200 +==== Understanding history: commits, parents, and reachability

201

202 Every commit (except the very first commit in a project) also has a

203 parent commit which shows what happened before this commit.

@@ -227,8 +221,7 @@ that Y is a descendant of X, or that there is a chain of parents

221 leading from commit Y to commit X.

222

223 [[history-diagrams]]

230 -Understanding history: History diagrams

231 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

224 +==== Understanding history: History diagrams

225

226 We will sometimes represent Git history using diagrams like the one

227 below. Commits are shown as "o", and the links between them with

@@ -247,8 +240,7 @@ If we need to talk about a particular commit, the character "o" may

240 be replaced with another letter or number.

241

242 [[what-is-a-branch]]

250 -Understanding history: What is a branch?

251 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

243 +==== Understanding history: What is a branch?

244

245 When we need to be precise, we will use the word "branch" to mean a line

246 of development, and "branch head" (or just "head") to mean a reference

@@ -261,8 +253,7 @@ However, when no confusion will result, we often just use the term

253 "branch" both for branches and for branch heads.

254

255 [[manipulating-branches]]

264 -Manipulating branches

265 ----------------------

256 +=== Manipulating branches

257

258 Creating, deleting, and modifying branches is quick and easy; here's

259 a summary of the commands:

@@ -299,8 +290,7 @@ ref: refs/heads/master

290 ------------------------------------------------

291

292 [[detached-head]]

302 -Examining an old version without creating a new branch

303 -------------------------------------------------------

293 +=== Examining an old version without creating a new branch

294

295 The `git switch` command normally expects a branch head, but will also

296 accept an arbitrary commit when invoked with --detach; for example,

@@ -340,8 +330,7 @@ make up a name for the new branch. You can still create a new branch

330 (or tag) for this version later if you decide to.

331

332 [[examining-remote-branches]]

343 -Examining branches from a remote repository

344 --------------------------------------------

333 +=== Examining branches from a remote repository

334

335 The "master" branch that was created at the time you cloned is a copy

336 of the HEAD in the repository that you cloned from. That repository

@@ -383,8 +372,7 @@ Note that the name "origin" is just the name that Git uses by default

372 to refer to the repository that you cloned from.

373

374 [[how-git-stores-references]]

386 -Naming branches, tags, and other references

387 --------------------------------------------

375 +=== Naming branches, tags, and other references

376

377 Branches, remote-tracking branches, and tags are all references to

378 commits. All references are named with a slash-separated path name

@@ -413,8 +401,7 @@ references with the same shorthand name, see the "SPECIFYING

401 REVISIONS" section of linkgit:gitrevisions[7].

402

403 [[Updating-a-repository-With-git-fetch]]

416 -Updating a repository with git fetch

417 -------------------------------------

404 +=== Updating a repository with git fetch

405

406 After you clone a repository and commit a few changes of your own, you

407 may wish to check the original repository for updates.

@@ -425,8 +412,7 @@ repository. It will not touch any of your own branches--not even the

412 "master" branch that was created for you on clone.

413

414 [[fetching-branches]]

428 -Fetching branches from other repositories

429 ------------------------------------------

415 +=== Fetching branches from other repositories

416

417 You can also track branches from repositories other than the one you

418 cloned from, using linkgit:git-remote[1]:

@@ -474,8 +460,7 @@ text editor. (See the "CONFIGURATION FILE" section of

460 linkgit:git-config[1] for details.)

461

462 [[exploring-git-history]]

477 -Exploring Git history

478 -=====================

463 +== Exploring Git history

464

465 Git is best thought of as a tool for storing the history of a

466 collection of files. It does this by storing compressed snapshots of

@@ -489,8 +474,7 @@ We start with one specialized tool that is useful for finding the

474 commit that introduced a bug into a project.

475

476 [[using-bisect]]

492 -How to use bisect to find a regression

493 ---------------------------------------

477 +=== How to use bisect to find a regression

478

479 Suppose version 2.6.18 of your project worked, but the version at

480 "master" crashes. Sometimes the best way to find the cause of such a

@@ -572,8 +556,7 @@ linkgit:git-bisect[1] for more information about this and other `git

556 bisect` features.

557

558 [[naming-commits]]

575 -Naming commits

576 ---------------

559 +=== Naming commits

560

561 We have seen several ways of naming commits already:

562

@@ -637,8 +620,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b

620 -------------------------------------------------

621

622 [[creating-tags]]

640 -Creating tags

641 --------------

623 +=== Creating tags

624

625 We can also create a tag to refer to a particular commit; after

626 running

@@ -655,8 +637,7 @@ should create a tag object instead; see the linkgit:git-tag[1] man page

637 for details.

638

639 [[browsing-revisions]]

658 -Browsing revisions

659 -------------------

640 +=== Browsing revisions

641

642 The linkgit:git-log[1] command can show lists of commits. On its

643 own, it shows all commits reachable from the parent commit; but you

@@ -697,8 +678,7 @@ multiple independent lines of development, the particular order that

678 commits are listed in may be somewhat arbitrary.

679

680 [[generating-diffs]]

700 -Generating diffs

701 -----------------

681 +=== Generating diffs

682

683 You can generate diffs between any two versions using

684 linkgit:git-diff[1]:

@@ -726,8 +706,7 @@ will generate a file with a patch for each commit reachable from test

706 but not from master.

707

708 [[viewing-old-file-versions]]

729 -Viewing old file versions

730 --------------------------

709 +=== Viewing old file versions

710

711 You can always view an old version of a file by just checking out the

712 correct revision first. But sometimes it is more convenient to be

@@ -742,12 +721,10 @@ Before the colon may be anything that names a commit, and after it

721 may be any path to a file tracked by Git.

722

723 [[history-examples]]

745 -Examples

746 ---------

724 +=== Examples

725

726 [[counting-commits-on-a-branch]]

749 -Counting the number of commits on a branch

750 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

727 +==== Counting the number of commits on a branch

728

729 Suppose you want to know how many commits you've made on `mybranch`

730 since it diverged from `origin`:

@@ -765,8 +742,7 @@ $ git rev-list origin..mybranch | wc -l

742 -------------------------------------------------

743

744 [[checking-for-equal-branches]]

768 -Check whether two branches point at the same history

769 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

745 +==== Check whether two branches point at the same history

746

747 Suppose you want to check whether two branches point at the same point

748 in history.

@@ -798,8 +774,7 @@ $ git log origin...master

774 will return no commits when the two branches are equal.

775

776 [[finding-tagged-descendants]]

801 -Find first tagged version including a given fix

802 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

777 +==== Find first tagged version including a given fix

778

779 Suppose you know that the commit e05db0fd fixed a certain problem.

780 You'd like to find the earliest tagged release that contains that

@@ -883,8 +858,7 @@ shows that e05db0fd is reachable from itself, from v1.5.0-rc1,

858 and from v1.5.0-rc2, and not from v1.5.0-rc0.

859

860 [[showing-commits-unique-to-a-branch]]

886 -Showing commits unique to a given branch

887 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

861 +==== Showing commits unique to a given branch

862

863 Suppose you would like to see all the commits reachable from the branch

864 head named `master` but not from any other head in your repository.

@@ -931,8 +905,7 @@ $ gitk $( git show-ref --heads ) --not $( git show-ref --tags )

905 syntax such as `--not`.)

906

907 [[making-a-release]]

934 -Creating a changelog and tarball for a software release

935 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

908 +==== Creating a changelog and tarball for a software release

909

910 The linkgit:git-archive[1] command can create a tar or zip archive from

911 any version of a project; for example:

@@ -983,8 +956,7 @@ and then he just cut-and-pastes the output commands after verifying that

956 they look OK.

957

958 [[Finding-commits-With-given-Content]]

986 -Finding commits referencing a file with given content

987 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

959 +==== Finding commits referencing a file with given content

960

961 Somebody hands you a copy of a file, and asks which commits modified a

962 file such that it contained the given content either before or after the

@@ -1000,12 +972,10 @@ student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and

972 linkgit:git-hash-object[1] man pages may prove helpful.

973

974 [[Developing-With-git]]

1003 -Developing with Git

1004 -===================

975 +== Developing with Git

976

977 [[telling-git-your-name]]

1007 -Telling Git your name

1008 ----------------------

978 +=== Telling Git your name

979

980 Before creating any commits, you should introduce yourself to Git.

981 The easiest way to do so is to use linkgit:git-config[1]:

@@ -1030,8 +1000,7 @@ also edit it with your favorite editor.

1000

1001

1002 [[creating-a-new-repository]]

1033 -Creating a new repository

1034 --------------------------

1003 +=== Creating a new repository

1004

1005 Creating a new repository from scratch is very easy:

1006

@@ -1052,8 +1021,7 @@ $ git commit

1021 -------------------------------------------------

1022

1023 [[how-to-make-a-commit]]

1055 -How to make a commit

1056 ---------------------

1024 +=== How to make a commit

1025

1026 Creating a new commit takes three steps:

1027

@@ -1148,8 +1116,7 @@ for inclusion in the index (by right-clicking on the diff hunk and

1116 choosing "Stage Hunk For Commit").

1117

1118 [[creating-good-commit-messages]]

1151 -Creating good commit messages

1152 ------------------------------

1119 +=== Creating good commit messages

1120

1121 Though not required, it's a good idea to begin the commit message

1122 with a single short (less than 50 character) line summarizing the

@@ -1162,8 +1129,7 @@ rest of the commit in the body.

1129

1130

1131 [[ignoring-files]]

1165 -Ignoring files

1166 ---------------

1132 +=== Ignoring files

1133

1134 A project will often generate files that you do 'not' want to track with Git.

1135 This typically includes files generated by a build process or temporary

@@ -1205,8 +1171,7 @@ Some Git commands can also take exclude patterns directly on the

1171 command line. See linkgit:gitignore[5] for the details.

1172

1173 [[how-to-merge]]

1208 -How to merge

1209 -------------

1174 +=== How to merge

1175

1176 You can rejoin two diverging branches of development using

1177 linkgit:git-merge[1]:

@@ -1254,8 +1219,7 @@ has two parents, one pointing to the top of the current branch, and

1219 one to the top of the other branch.

1220

1221 [[resolving-a-merge]]

1257 -Resolving a merge

1258 ------------------

1222 +=== Resolving a merge

1223

1224 When a merge isn't resolved automatically, Git leaves the index and

1225 the working tree in a special state that gives you all the

@@ -1297,8 +1261,7 @@ The above is all you need to know to resolve a simple merge. But Git

1261 also provides more information to help resolve conflicts:

1262

1263 [[conflict-resolution]]

1300 -Getting conflict-resolution help during a merge

1301 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1264 +==== Getting conflict-resolution help during a merge

1265

1266 All of the changes that Git was able to merge automatically are

1267 already added to the index file, so linkgit:git-diff[1] shows only

@@ -1401,8 +1364,7 @@ the different stages of that file will be "collapsed", after which

1364 `git diff` will (by default) no longer show diffs for that file.

1365

1366 [[undoing-a-merge]]

1404 -Undoing a merge

1405 ----------------

1367 +=== Undoing a merge

1368

1369 If you get stuck and decide to just give up and throw the whole mess

1370 away, you can always return to the pre-merge state with

@@ -1423,8 +1385,7 @@ itself have been merged into another branch, as doing so may confuse

1385 further merges.

1386

1387 [[fast-forwards]]

1426 -Fast-forward merges

1427 --------------------

1388 +=== Fast-forward merges

1389

1390 There is one special case not mentioned above, which is treated

1391 differently. Normally, a merge results in a merge commit, with two

@@ -1438,8 +1399,7 @@ to point at the head of the merged-in branch, without any new commits being

1399 created.

1400

1401 [[fixing-mistakes]]

1441 -Fixing mistakes

1442 ----------------

1402 +=== Fixing mistakes

1403

1404 If you've messed up the working tree, but haven't yet committed your

1405 mistake, you can return the entire working tree to the last committed

@@ -1463,8 +1423,7 @@ fundamentally different ways to fix the problem:

1423 a branch that has had its history changed.

1424

1425 [[reverting-a-commit]]

1466 -Fixing a mistake with a new commit

1467 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1426 +==== Fixing a mistake with a new commit

1427

1428 Creating a new commit that reverts an earlier change is very easy;

1429 just pass the linkgit:git-revert[1] command a reference to the bad

@@ -1490,8 +1449,7 @@ conflicts manually, just as in the case of <<resolving-a-merge,

1449 resolving a merge>>.

1450

1451 [[fixing-a-mistake-by-rewriting-history]]

1493 -Fixing a mistake by rewriting history

1494 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1452 +==== Fixing a mistake by rewriting history

1453

1454 If the problematic commit is the most recent commit, and you have not

1455 yet made that commit public, then you may just

@@ -1518,8 +1476,7 @@ this is an advanced topic to be left for

1476 <<cleaning-up-history,another chapter>>.

1477

1478 [[checkout-of-path]]

1521 -Checking out an old version of a file

1522 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1479 +==== Checking out an old version of a file

1480

1481 In the process of undoing a previous bad change, you may find it

1482 useful to check out an older version of a particular file using

@@ -1543,8 +1500,7 @@ $ git show HEAD^:path/to/file

1500 which will display the given version of the file.

1501

1502 [[interrupted-work]]

1546 -Temporarily setting aside work in progress

1547 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1503 +==== Temporarily setting aside work in progress

1504

1505 While you are in the middle of working on something complicated, you

1506 find an unrelated but obvious and trivial bug. You would like to fix it

@@ -1575,8 +1531,7 @@ $ git stash pop

1531

1532

1533 [[ensuring-good-performance]]

1578 -Ensuring good performance

1579 --------------------------

1534 +=== Ensuring good performance

1535

1536 On large repositories, Git depends on compression to keep the history

1537 information from taking up too much space on disk or in memory. Some

@@ -1587,12 +1542,10 @@ to avoid automatic compression kicking in when it is not convenient.

1542

1543

1544 [[ensuring-reliability]]

1590 -Ensuring reliability

1591 ---------------------

1545 +=== Ensuring reliability

1546

1547 [[checking-for-corruption]]

1594 -Checking the repository for corruption

1595 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1548 +==== Checking the repository for corruption

1549

1550 The linkgit:git-fsck[1] command runs a number of self-consistency checks

1551 on the repository, and reports on any problems. This may take some

@@ -1618,12 +1571,10 @@ You can run `git fsck --no-dangling` to suppress these messages, and still

1571 view real errors.

1572

1573 [[recovering-lost-changes]]

1621 -Recovering lost changes

1622 -~~~~~~~~~~~~~~~~~~~~~~~

1574 +==== Recovering lost changes

1575

1576 [[reflogs]]

1625 -Reflogs

1626 -^^^^^^^

1577 +===== Reflogs

1578

1579 Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,

1580 and then realize that the branch was the only reference you had to

@@ -1670,8 +1621,7 @@ same project, the reflog history is not shared: it tells you only about

1621 how the branches in your local repository have changed over time.

1622

1623 [[dangling-object-recovery]]

1673 -Examining dangling objects

1674 -^^^^^^^^^^^^^^^^^^^^^^^^^^

1624 +===== Examining dangling objects

1625

1626 In some situations the reflog may not be able to save you. For example,

1627 suppose you delete a branch, then realize you need the history it

@@ -1715,12 +1665,10 @@ dangling objects can arise in other situations.

1665

1666

1667 [[sharing-development]]

1718 -Sharing development with others

1719 -===============================

1668 +== Sharing development with others

1669

1670 [[getting-updates-With-git-pull]]

1722 -Getting updates with git pull

1723 ------------------------------

1671 +=== Getting updates with git pull

1672

1673 After you clone a repository and commit a few changes of your own, you

1674 may wish to check the original repository for updates and merge them

@@ -1783,8 +1731,7 @@ $ git merge branch

1731 are roughly equivalent.

1732

1733 [[submitting-patches]]

1786 -Submitting patches to a project

1787 --------------------------------

1734 +=== Submitting patches to a project

1735

1736 If you just have a few changes, the simplest way to submit them may

1737 just be to send them as patches in email:

@@ -1812,8 +1759,7 @@ Consult the mailing list for your project first to determine

1759 their requirements for submitting patches.

1760

1761 [[importing-patches]]

1815 -Importing patches to a project

1816 -------------------------------

1762 +=== Importing patches to a project

1763

1764 Git also provides a tool called linkgit:git-am[1] (am stands for

1765 "apply mailbox"), for importing such an emailed series of patches.

@@ -1845,8 +1791,7 @@ the original mailbox, with authorship and commit log message each

1791 taken from the message containing each patch.

1792

1793 [[public-repositories]]

1848 -Public Git repositories

1849 ------------------------

1794 +=== Public Git repositories

1795

1796 Another way to submit changes to a project is to tell the maintainer

1797 of that project to pull the changes from your repository using

@@ -1899,8 +1844,7 @@ like this:

1844 We explain how to do this in the following sections.

1845

1846 [[setting-up-a-public-repository]]

1902 -Setting up a public repository

1903 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1847 +==== Setting up a public repository

1848

1849 Assume your personal repository is in the directory `~/proj`. We

1850 first create a new clone of the repository and tell `git daemon` that it

@@ -1920,8 +1864,7 @@ public repository. You can use scp, rsync, or whatever is most

1864 convenient.

1865

1866 [[exporting-via-git]]

1923 -Exporting a Git repository via the Git protocol

1924 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1867 +==== Exporting a Git repository via the Git protocol

1868

1869 This is the preferred method.

1870

@@ -1942,8 +1885,7 @@ linkgit:git-daemon[1] man page for details. (See especially the

1885 examples section.)

1886

1887 [[exporting-via-http]]

1945 -Exporting a git repository via HTTP

1946 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1888 +==== Exporting a git repository via HTTP

1889

1890 The Git protocol gives better performance and reliability, but on a

1891 host with a web server set up, HTTP exports may be simpler to set up.

@@ -1975,8 +1917,7 @@ for a slightly more sophisticated setup using WebDAV which also

1917 allows pushing over HTTP.)

1918

1919 [[pushing-changes-to-a-public-repository]]

1978 -Pushing changes to a public repository

1979 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1920 +==== Pushing changes to a public repository

1921

1922 Note that the two techniques outlined above (exporting via

1923 <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other

@@ -2035,8 +1976,7 @@ See the explanations of the `remote.<name>.url`,

1976 linkgit:git-config[1] for details.

1977

1978 [[forcing-push]]

2038 -What to do when a push fails

2039 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1979 +==== What to do when a push fails

1980

1981 If a push would not result in a <<fast-forwards,fast-forward>> of the

1982 remote branch, then it will fail with an error like:

@@ -2090,8 +2030,7 @@ pull, or by a fetch followed by a rebase; see the

2030 linkgit:gitcvs-migration[7] for more.

2031

2032 [[setting-up-a-shared-repository]]

2093 -Setting up a shared repository

2094 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2033 +==== Setting up a shared repository

2034

2035 Another way to collaborate is by using a model similar to that

2036 commonly used in CVS, where several developers with special rights

@@ -2121,8 +2060,7 @@ advantages over the central shared repository:

2060 "out".

2061

2062 [[setting-up-gitweb]]

2124 -Allowing web browsing of a repository

2125 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2063 +==== Allowing web browsing of a repository

2064

2065 The gitweb cgi script provides users an easy way to browse your

2066 project's revisions, file contents and logs without having to install

@@ -2138,8 +2076,7 @@ linkgit:gitweb[1] for instructions on details setting up a permanent

2076 installation with a CGI or Perl capable server.

2077

2078 [[how-to-get-a-git-repository-with-minimal-history]]

2141 -How to get a Git repository with minimal history

2142 -------------------------------------------------

2079 +=== How to get a Git repository with minimal history

2080

2081 A <<def_shallow_clone,shallow clone>>, with its truncated

2082 history, is useful when one is interested only in recent history

@@ -2158,12 +2095,10 @@ have to result in huge conflicts. This limitation may make such

2095 a repository unsuitable to be used in merge based workflows.

2096

2097 [[sharing-development-examples]]

2161 -Examples

2162 ---------

2098 +=== Examples

2099

2100 [[maintaining-topic-branches]]

2165 -Maintaining topic branches for a Linux subsystem maintainer

2166 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2101 +==== Maintaining topic branches for a Linux subsystem maintainer

2102

2103 This describes how Tony Luck uses Git in his role as maintainer of the

2104 IA64 architecture for the Linux kernel.

@@ -2459,8 +2394,7 @@ done

2394

2395

2396 [[cleaning-up-history]]

2462 -Rewriting history and maintaining patch series

2463 -==============================================

2397 +== Rewriting history and maintaining patch series

2398

2399 Normally commits are only added to a project, never taken away or

2400 replaced. Git is designed with this assumption, and violating it will

@@ -2470,8 +2404,7 @@ However, there is a situation in which it can be useful to violate this

2404 assumption.

2405

2406 [[patch-series]]

2473 -Creating the perfect patch series

2474 ----------------------------------

2407 +=== Creating the perfect patch series

2408

2409 Suppose you are a contributor to a large project, and you want to add a

2410 complicated feature, and to present it to the other developers in a way

@@ -2503,8 +2436,7 @@ use them, and then explain some of the problems that can arise because

2436 you are rewriting history.

2437

2438 [[using-git-rebase]]

2506 -Keeping a patch series up to date using git rebase

2507 ---------------------------------------------------

2439 +=== Keeping a patch series up to date using git rebase

2440

2441 Suppose that you create a branch `mywork` on a remote-tracking branch

2442 `origin`, and create some commits on top of it:

@@ -2591,8 +2523,7 @@ the rebase. See <<interactive-rebase>> for details, and

2523 <<reordering-patch-series>> for alternatives.

2524

2525 [[rewriting-one-commit]]

2594 -Rewriting a single commit

2595 --------------------------

2526 +=== Rewriting a single commit

2527

2528 We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the

2529 most recent commit using

@@ -2610,8 +2541,7 @@ If you need to amend commits from deeper in your history, you can

2541 use <<interactive-rebase,interactive rebase's `edit` instruction>>.

2542

2543 [[reordering-patch-series]]

2613 -Reordering or selecting from a patch series

2614 --------------------------------------------

2544 +=== Reordering or selecting from a patch series

2545

2546 Sometimes you want to edit a commit deeper in your history. One

2547 approach is to use `git format-patch` to create a series of patches

@@ -2630,8 +2560,7 @@ $ git am *.patch

2560 -------------------------------------------------

2561

2562 [[interactive-rebase]]

2633 -Using interactive rebases

2634 --------------------------

2563 +=== Using interactive rebases

2564

2565 You can also edit a patch series with an interactive rebase. This is

2566 the same as <<reordering-patch-series,reordering a patch series using

@@ -2688,16 +2617,14 @@ For a more detailed discussion of the procedure and additional tips,

2617 see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].

2618

2619 [[patch-series-tools]]

2691 -Other tools

2692 ------------

2620 +=== Other tools

2621

2622 There are numerous other tools, such as StGit, which exist for the

2623 purpose of maintaining a patch series. These are outside of the scope of

2624 this manual.

2625

2626 [[problems-With-rewriting-history]]

2699 -Problems with rewriting history

2700 --------------------------------

2627 +=== Problems with rewriting history

2628

2629 The primary problem with rewriting the history of a branch has to do

2630 with merging. Suppose somebody fetches your branch and merges it into

@@ -2745,8 +2672,7 @@ For true distributed development that supports proper merging,

2672 published branches should never be rewritten.

2673

2674 [[bisect-merges]]

2748 -Why bisecting merge commits can be harder than bisecting linear history

2749 ------------------------------------------------------------------------

2675 +=== Why bisecting merge commits can be harder than bisecting linear history

2676

2677 The linkgit:git-bisect[1] command correctly handles history that

2678 includes merge commits. However, when the commit that it finds is a

@@ -2811,12 +2737,10 @@ linear by rebasing against the latest upstream version before

2737 publishing.

2738

2739 [[advanced-branch-management]]

2814 -Advanced branch management

2815 -==========================

2740 +== Advanced branch management

2741

2742 [[fetching-individual-branches]]

2818 -Fetching individual branches

2819 -----------------------------

2743 +=== Fetching individual branches

2744

2745 Instead of using linkgit:git-remote[1], you can also choose just

2746 to update one branch at a time, and to store it locally under an

@@ -2844,8 +2768,7 @@ already have a branch named example-master, it will attempt to

2768 master branch. In more detail:

2769

2770 [[fetch-fast-forwards]]

2847 -git fetch and fast-forwards

2848 ----------------------------

2771 +=== git fetch and fast-forwards

2772

2773 In the previous example, when updating an existing branch, `git fetch`

2774 checks to make sure that the most recent commit on the remote

@@ -2882,8 +2805,7 @@ unless you've already created a reference of your own pointing to

2805 them.

2806

2807 [[forcing-fetch]]

2885 -Forcing git fetch to do non-fast-forward updates

2886 -------------------------------------------------

2808 +=== Forcing git fetch to do non-fast-forward updates

2809

2810 If git fetch fails because the new head of a branch is not a

2811 descendant of the old head, you may force the update with:

@@ -2903,8 +2825,7 @@ Be aware that commits that the old version of example/master pointed at

2825 may be lost, as we saw in the previous section.

2826

2827 [[remote-branch-configuration]]

2906 -Configuring remote-tracking branches

2907 -------------------------------------

2828 +=== Configuring remote-tracking branches

2829

2830 We saw above that `origin` is just a shortcut to refer to the

2831 repository that you originally cloned from. This information is

@@ -2955,8 +2876,7 @@ the refspec syntax.

2876

2877

2878 [[git-concepts]]

2958 -Git concepts

2959 -============

2879 +== Git concepts

2880

2881 Git is built on a small number of simple but powerful ideas. While it

2882 is possible to get things done without understanding them, you will find

@@ -2966,8 +2886,7 @@ We start with the most important, the <<def_object_database,object

2886 database>> and the <<def_index,index>>.

2887

2888 [[the-object-database]]

2969 -The Object Database

2970 --------------------

2889 +=== The Object Database

2890

2891

2892 We already saw in <<understanding-commits>> that all commits are stored

@@ -3011,8 +2930,7 @@ There are four different types of objects: "blob", "tree", "commit", and

2930 The object types in some more detail:

2931

2932 [[commit-object]]

3014 -Commit Object

3015 -~~~~~~~~~~~~~

2933 +==== Commit Object

2934

2935 The "commit" object links a physical state of a tree with a description

2936 of how we got there and why. Use the `--pretty=raw` option to

@@ -3064,8 +2982,7 @@ commit whose parent is normally the current HEAD, and whose tree is

2982 taken from the content currently stored in the index.

2983

2984 [[tree-object]]

3067 -Tree Object

3068 -~~~~~~~~~~~

2985 +==== Tree Object

2986

2987 The ever-versatile linkgit:git-show[1] command can also be used to

2988 examine tree objects, but linkgit:git-ls-tree[1] will give you more

@@ -3104,8 +3021,7 @@ Note that the files all have mode 644 or 755: Git actually only pays

3021 attention to the executable bit.

3022

3023 [[blob-object]]

3107 -Blob Object

3108 -~~~~~~~~~~~

3024 +==== Blob Object

3025

3026 You can use linkgit:git-show[1] to examine the contents of a blob; take,

3027 for example, the blob in the entry for `COPYING` from the tree above:

@@ -3134,8 +3050,7 @@ sometimes be useful for browsing the contents of a tree that is not

3050 currently checked out.

3051

3052 [[trust]]

3137 -Trust

3138 -~~~~~

3053 +==== Trust

3054

3055 If you receive the SHA-1 name of a blob from one source, and its contents

3056 from another (possibly untrusted) source, you can still trust that those

@@ -3164,8 +3079,7 @@ like GPG/PGP.

3079 To assist in this, Git also provides the tag object...

3080

3081 [[tag-object]]

3167 -Tag Object

3168 -~~~~~~~~~~

3082 +==== Tag Object

3083

3084 A tag object contains an object, object type, tag name, the name of the

3085 person ("tagger") who created the tag, and a message, which may contain

@@ -3194,8 +3108,7 @@ objects. (Note that linkgit:git-tag[1] can also be used to create

3108 references whose names begin with `refs/tags/`).

3109

3110 [[pack-files]]

3197 -How Git stores objects efficiently: pack files

3198 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3111 +==== How Git stores objects efficiently: pack files

3112

3113 Newly created objects are initially created in a file named after the

3114 object's SHA-1 hash (stored in `.git/objects`).

@@ -3253,8 +3166,7 @@ The linkgit:git-gc[1] command performs packing, pruning, and more for

3166 you, so is normally the only high-level command you need.

3167

3168 [[dangling-objects]]

3256 -Dangling objects

3257 -~~~~~~~~~~~~~~~~

3169 +==== Dangling objects

3170

3171 The linkgit:git-fsck[1] command will sometimes complain about dangling

3172 objects. They are not a problem.

@@ -3334,8 +3246,7 @@ don't want to do that while the filesystem is mounted.

3246 accesses to a repository but you might receive confusing or scary messages.)

3247

3248 [[recovering-from-repository-corruption]]

3337 -Recovering from repository corruption

3338 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3249 +==== Recovering from repository corruption

3250

3251 By design, Git treats data trusted to it with caution. However, even in

3252 the absence of bugs in Git itself, it is still possible that hardware or

@@ -3452,8 +3363,7 @@ whole thing. It's up to you--Git does *have* a lot of information, it is

3363 just missing one particular blob version.

3364

3365 [[the-index]]

3455 -The index

3456 ----------

3366 +=== The index

3367

3368 The index is a binary file (generally kept in `.git/index`) containing a

3369 sorted list of path names, each with permissions and the SHA-1 of a blob

@@ -3511,8 +3421,7 @@ If you blow the index away entirely, you generally haven't lost any

3421 information as long as you have the name of the tree that it described.

3422

3423 [[submodules]]

3514 -Submodules

3515 -==========

3424 +== Submodules

3425

3426 Large projects are often composed of smaller, self-contained modules. For

3427 example, an embedded Linux distribution's source tree would include every

@@ -3699,8 +3608,7 @@ You have to run `git submodule update` after `git pull` if you want to update

3608 submodules, too.

3609

3610 [[pitfalls-with-submodules]]

3702 -Pitfalls with submodules

3703 -------------------------

3611 +=== Pitfalls with submodules

3612

3613 Always publish the submodule change before publishing the change to the

3614 superproject that references it. If you forget to publish the submodule change,

@@ -3769,8 +3677,7 @@ submodule update` will not overwrite them. Instead, you get the usual

3677 warning about not being able switch from a dirty branch.

3678

3679 [[low-level-operations]]

3772 -Low-level Git operations

3773 -========================

3680 +== Low-level Git operations

3681

3682 Many of the higher-level commands were originally implemented as shell

3683 scripts using a smaller core of low-level Git commands. These can still

@@ -3778,8 +3685,7 @@ be useful when doing unusual things with Git, or just as a way to

3685 understand its inner workings.

3686

3687 [[object-manipulation]]

3781 -Object access and manipulation

3782 -------------------------------

3688 +=== Object access and manipulation

3689

3690 The linkgit:git-cat-file[1] command can show the contents of any object,

3691 though the higher-level linkgit:git-show[1] is usually more useful.

@@ -3796,8 +3702,7 @@ verified by linkgit:git-verify-tag[1], though it is normally simpler to

3702 use linkgit:git-tag[1] for both.

3703

3704 [[the-workflow]]

3799 -The Workflow

3800 -------------

3705 +=== The Workflow

3706

3707 High-level operations such as linkgit:git-commit[1] and

3708 linkgit:git-restore[1] work by moving data

@@ -3812,8 +3717,7 @@ the database or the working directory. Thus there are four main

3717 combinations:

3718

3719 [[working-directory-to-index]]

3815 -working directory -> index

3816 -~~~~~~~~~~~~~~~~~~~~~~~~~~

3720 +==== working directory -> index

3721

3722 The linkgit:git-update-index[1] command updates the index with

3723 information from the working directory. You generally update the

@@ -3849,8 +3753,7 @@ The previously introduced linkgit:git-add[1] is just a wrapper for

3753 linkgit:git-update-index[1].

3754

3755 [[index-to-object-database]]

3852 -index -> object database

3853 -~~~~~~~~~~~~~~~~~~~~~~~~

3756 +==== index -> object database

3757

3758 You write your current index file to a "tree" object with the program

3759

@@ -3865,8 +3768,7 @@ use that tree to re-generate the index at any time by going in the

3768 other direction:

3769

3770 [[object-database-to-index]]

3868 -object database -> index

3869 -~~~~~~~~~~~~~~~~~~~~~~~~

3771 +==== object database -> index

3772

3773 You read a "tree" file from the object database, and use that to

3774 populate (and overwrite--don't do this if your index contains any

@@ -3882,8 +3784,7 @@ earlier. However, that is only your 'index' file: your working

3784 directory contents have not been modified.

3785

3786 [[index-to-working-directory]]

3885 -index -> working directory

3886 -~~~~~~~~~~~~~~~~~~~~~~~~~~

3787 +==== index -> working directory

3788

3789 You update your working directory from the index by "checking out"

3790 files. This is not a very common operation, since normally you'd just

@@ -3912,8 +3813,7 @@ Finally, there are a few odds and ends which are not purely moving

3813 from one representation to the other:

3814

3815 [[tying-it-all-together]]

3915 -Tying it all together

3916 -~~~~~~~~~~~~~~~~~~~~~

3816 +==== Tying it all together

3817

3818 To commit a tree you have instantiated with `git write-tree`, you'd

3819 create a "commit" object that refers to that tree and the history

@@ -3987,8 +3887,7 @@ Here is a picture that illustrates how various pieces fit together:

3887

3888

3889 [[examining-the-data]]

3990 -Examining the data

3991 -------------------

3890 +=== Examining the data

3891

3892 You can examine the data represented in the object database and the

3893 index with various helper tools. For every object, you can use

@@ -4023,8 +3922,7 @@ $ git cat-file commit HEAD

3922 to see what the top commit was.

3923

3924 [[merging-multiple-trees]]

4026 -Merging multiple trees

4027 -----------------------

3925 +=== Merging multiple trees

3926

3927 Git can help you perform a three-way merge, which can in turn be

3928 used for a many-way merge by repeating the merge procedure several

@@ -4074,8 +3972,7 @@ index file, and you can just write the result out with

3972

3973

3974 [[merging-multiple-trees-2]]

4077 -Merging multiple trees, continued

4078 ----------------------------------

3975 +=== Merging multiple trees, continued

3976

3977 Sadly, many merges aren't trivial. If there are files that have

3978 been added, moved or removed, or if both branches have modified the

@@ -4145,15 +4042,13 @@ $ git merge-index git-merge-one-file hello.c

4042 and that is what higher level `git merge -s resolve` is implemented with.

4043

4044 [[hacking-git]]

4148 -Hacking Git

4149 -===========

4045 +== Hacking Git

4046

4047 This chapter covers internal details of the Git implementation which

4048 probably only Git developers need to understand.

4049

4050 [[object-details]]

4155 -Object storage format

4156 ----------------------

4051 +=== Object storage format

4052

4053 All objects have a statically determined "type" which identifies the

4054 format of the object (i.e. how it is used, and how it can refer to other

@@ -4183,8 +4078,7 @@ of all objects, and verifies their internal consistency (in addition

4078 to just verifying their superficial consistency through the hash).

4079

4080 [[birdview-on-the-source-code]]

4186 -A birds-eye view of Git's source code

4187 --------------------------------------

4081 +=== A birds-eye view of Git's source code

4082

4083 It is not always easy for new developers to find their way through Git's

4084 source code. This section gives you a little guidance to show where to

@@ -4393,25 +4287,22 @@ You see, Git is actually the best tool to find out about the source of Git

4287 itself!

4288

4289 [[glossary]]

4396 -Git Glossary

4397 -============

4290 +== Git Glossary

4291

4292 [[git-explained]]

4400 -Git explained

4401 --------------

4293 +=== Git explained

4294

4295 include::glossary-content.txt[]

4296

4297 [[git-quick-start]]

4406 -Appendix A: Git Quick Reference

4407 -===============================

4298 +[appendix]

4299 +== Git Quick Reference

4300

4301 This is a quick summary of the major commands; the previous chapters

4302 explain how these work in more detail.

4303

4304 [[quick-creating-a-new-repository]]

4413 -Creating a new repository

4414 --------------------------

4305 +=== Creating a new repository

4306

4307 From a tarball:

4308

@@ -4432,8 +4323,7 @@ $ cd project

4323 -----------------------------------------------

4324

4325 [[managing-branches]]

4435 -Managing branches

4436 ------------------

4326 +=== Managing branches

4327

4328 -----------------------------------------------

4329 $ git branch # list all local branches in this repo

@@ -4497,8 +4387,7 @@ $ git branch -r # list all remote branches

4387

4388

4389 [[exploring-history]]

4500 -Exploring history

4501 ------------------

4390 +=== Exploring history

4391

4392 -----------------------------------------------

4393 $ gitk # visualize and browse history

@@ -4533,8 +4422,7 @@ $ git bisect bad # if this revision is bad.

4422 -----------------------------------------------

4423

4424 [[making-changes]]

4536 -Making changes

4537 ---------------

4425 +=== Making changes

4426

4427 Make sure Git knows who to blame:

4428

@@ -4564,8 +4452,7 @@ $ git commit -a # use latest content of all tracked files

4452 -----------------------------------------------

4453

4454 [[merging]]

4567 -Merging

4568 --------

4455 +=== Merging

4456

4457 -----------------------------------------------

4458 $ git merge test # merge branch "test" into the current branch

@@ -4575,8 +4462,7 @@ $ git pull . test # equivalent to git merge test

4462 -----------------------------------------------

4463

4464 [[sharing-your-changes]]

4578 -Sharing your changes

4579 ---------------------

4465 +=== Sharing your changes

4466

4467 Importing or exporting patches:

4468

@@ -4621,8 +4507,7 @@ $ git push example test

4507 -----------------------------------------------

4508

4509 [[repository-maintenance]]

4624 -Repository maintenance

4625 -----------------------

4510 +=== Repository maintenance

4511

4512 Check for corruption:

4513

@@ -4638,12 +4523,11 @@ $ git gc

4523

4524

4525 [[todo]]

4641 -Appendix B: Notes and todo list for this manual

4642 -===============================================

4526 +[appendix]

4527 +== Notes and todo list for this manual

4528

4529 [[todo-list]]

4645 -Todo list

4646 ----------

4530 +=== Todo list

4531

4532 This is a work in progress.

4533

user-manual.txt: change header notation