Package: git-man
Version: 1:2.45.2-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-][gn]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':2110
troff:<stdin>:2110: warning: [page 21, 7.3i]: cannot break line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':2110
troff:<stdin>:2110: warning: [page 22, line 47]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.10.9-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
-- no debconf information
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of \'nroff -mandoc\'
Add the option \'-t\', if the file contains a table.
Read the output of \'diff -u\' with \'less -R\' or similar.
-.-.
If \'man\' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint gitcore-tutorial.7": (possibly shortened list)
mandoc: gitcore-tutorial.7:33:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:36:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:37:101: STYLE: input text line longer than 80 bytes:
This tutorial explai...
mandoc: gitcore-tutorial.7:39:202: STYLE: input text line longer than 80 bytes:
If you just need to ...
mandoc: gitcore-tutorial.7:41:114: STYLE: input text line longer than 80 bytes:
However, an understa...
mandoc: gitcore-tutorial.7:43:257: STYLE: input text line longer than 80 bytes:
The core Git is ofte...
mandoc: gitcore-tutorial.7:45:436: STYLE: input text line longer than 80 bytes:
Back when this docum...
mandoc: gitcore-tutorial.7:55:2: WARNING: skipping paragraph macro: br before sp
mandoc: gitcore-tutorial.7:57:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:59:95: STYLE: input text line longer than 80 bytes:
Deeper technical det...
mandoc: gitcore-tutorial.7:63:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:64:309: STYLE: input text line longer than 80 bytes:
Creating a new Git r...
mandoc: gitcore-tutorial.7:66:291: STYLE: input text line longer than 80 bytes:
For our first exampl...
mandoc: gitcore-tutorial.7:94:344: STYLE: input text line longer than 80 bytes:
which is just Git\(c...
mandoc: gitcore-tutorial.7:115:100: STYLE: input text line longer than 80
bytes: link points to doesn...
mandoc: gitcore-tutorial.7:146:362: STYLE: input text line longer than 80
bytes: In particular, the \...
mandoc: gitcore-tutorial.7:148:338: STYLE: input text line longer than 80
bytes: One note: the specia...
mandoc: gitcore-tutorial.7:150:233: STYLE: input text line longer than 80
bytes: However, this is onl...
mandoc: gitcore-tutorial.7:160:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:162:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:164:478: STYLE: input text line longer than 80
bytes: An \fIobject\fR is i...
mandoc: gitcore-tutorial.7:176:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:178:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:180:106: STYLE: input text line longer than 80
bytes: An advanced user may...
mandoc: gitcore-tutorial.7:184:153: STYLE: input text line longer than 80
bytes: You have now created...
mandoc: gitcore-tutorial.7:186:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:187:124: STYLE: input text line longer than 80
bytes: We\(cqll keep this s...
mandoc: gitcore-tutorial.7:189:180: STYLE: input text line longer than 80
bytes: Start off with just ...
mandoc: gitcore-tutorial.7:203:162: STYLE: input text line longer than 80
bytes: you have now created...
mandoc: gitcore-tutorial.7:230:461: STYLE: input text line longer than 80
bytes: The first step is tr...
mandoc: gitcore-tutorial.7:247:218: STYLE: input text line longer than 80
bytes: In fact, as you did ...
mandoc: gitcore-tutorial.7:274:109: STYLE: input text line longer than 80
bytes: which correspond wit...
mandoc: gitcore-tutorial.7:276:148: STYLE: input text line longer than 80
bytes: If you want to, you ...
mandoc: gitcore-tutorial.7:289:208: STYLE: input text line longer than 80
bytes: where the \fB\-t\fR ...
mandoc: gitcore-tutorial.7:302:124: STYLE: input text line longer than 80
bytes: which will print out...
mandoc: gitcore-tutorial.7:312:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:314:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:316:279: STYLE: input text line longer than 80
bytes: Don\(cqt confuse tha...
mandoc: gitcore-tutorial.7:328:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:330:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:332:134: STYLE: input text line longer than 80
bytes: The second example d...
mandoc: gitcore-tutorial.7:336:364: STYLE: input text line longer than 80
bytes: Anyway, as we mentio...
mandoc: gitcore-tutorial.7:338:403: STYLE: input text line longer than 80
bytes: Updating the index d...
mandoc: gitcore-tutorial.7:340:147: STYLE: input text line longer than 80
bytes: However, since Git k...
mandoc: gitcore-tutorial.7:342:133: STYLE: input text line longer than 80
bytes: In particular, let\(...
mandoc: gitcore-tutorial.7:355:182: STYLE: input text line longer than 80
bytes: and you can now, sin...
mandoc: gitcore-tutorial.7:368:280: STYLE: input text line longer than 80
bytes: Oops\&. That wasn\(c...
mandoc: gitcore-tutorial.7:370:118: STYLE: input text line longer than 80
bytes: To make it readable,...
mandoc: gitcore-tutorial.7:390:82: STYLE: input text line longer than 80 bytes:
i\&.e\&. the diff of...
mandoc: gitcore-tutorial.7:392:177: STYLE: input text line longer than 80
bytes: In other words, \fIg...
mandoc: gitcore-tutorial.7:394:113: STYLE: input text line longer than 80
bytes: A common shorthand f...
mandoc: gitcore-tutorial.7:414:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:415:375: STYLE: input text line longer than 80
bytes: Now, we want to go t...
mandoc: gitcore-tutorial.7:417:408: STYLE: input text line longer than 80
bytes: Creating a tree obje...
mandoc: gitcore-tutorial.7:430:131: STYLE: input text line longer than 80
bytes: and this will just o...
mandoc: gitcore-tutorial.7:443:355: STYLE: input text line longer than 80
bytes: which is another inc...
mandoc: gitcore-tutorial.7:445:341: STYLE: input text line longer than 80
bytes: However \(em normall...
mandoc: gitcore-tutorial.7:449:322: STYLE: input text line longer than 80
bytes: And this is where we...
mandoc: gitcore-tutorial.7:464:213: STYLE: input text line longer than 80
bytes: In this case this cr...
mandoc: gitcore-tutorial.7:466:261: STYLE: input text line longer than 80
bytes: Again, normally you\...
mandoc: gitcore-tutorial.7:468:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:469:200: STYLE: input text line longer than 80
bytes: Remember how we did ...
mandoc: gitcore-tutorial.7:471:403: STYLE: input text line longer than 80
bytes: Further, remember ho...
mandoc: gitcore-tutorial.7:473:314: STYLE: input text line longer than 80
bytes: As before, if we do ...
mandoc: gitcore-tutorial.7:475:407: STYLE: input text line longer than 80
bytes: Unlike \fIgit diff\-...
mandoc: gitcore-tutorial.7:490:346: STYLE: input text line longer than 80
bytes: (where \fB\-p\fR has...
mandoc: gitcore-tutorial.7:507:431: STYLE: input text line longer than 80
bytes: In other words, \fIg...
mandoc: gitcore-tutorial.7:517:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:519:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:523:290: STYLE: input text line longer than 80
bytes: This is not hard to ...
mandoc: gitcore-tutorial.7:527:377: STYLE: input text line longer than 80
bytes: However, our next st...
mandoc: gitcore-tutorial.7:540:103: STYLE: input text line longer than 80
bytes: (note how we didn\(c...
mandoc: gitcore-tutorial.7:542:461: STYLE: input text line longer than 80
bytes: Note what happens to...
mandoc: gitcore-tutorial.7:544:426: STYLE: input text line longer than 80
bytes: Now, since we\(cqve ...
mandoc: gitcore-tutorial.7:557:106: STYLE: input text line longer than 80
bytes: which starts an edit...
mandoc: gitcore-tutorial.7:559:391: STYLE: input text line longer than 80
bytes: Write whatever messa...
mandoc: gitcore-tutorial.7:561:322: STYLE: input text line longer than 80
bytes: You\(cqve now made y...
mandoc: gitcore-tutorial.7:563:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:564:197: STYLE: input text line longer than 80
bytes: While creating chang...
mandoc: gitcore-tutorial.7:579:149: STYLE: input text line longer than 80
bytes: (again, \fB\-p\fR me...
mandoc: gitcore-tutorial.7:589:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:591:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:593:106: STYLE: input text line longer than 80
bytes: Here is an ASCII art...
mandoc: gitcore-tutorial.7:634:343: STYLE: input text line longer than 80
bytes: More interestingly, ...
mandoc: gitcore-tutorial.7:636:393: STYLE: input text line longer than 80
bytes: In fact, together wi...
mandoc: gitcore-tutorial.7:638:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:641:210: STYLE: input text line longer than 80
bytes: A "light" tag is tec...
mandoc: gitcore-tutorial.7:654:201: STYLE: input text line longer than 80
bytes: which just writes th...
mandoc: gitcore-tutorial.7:667:235: STYLE: input text line longer than 80
bytes: to diff your current...
mandoc: gitcore-tutorial.7:669:329: STYLE: input text line longer than 80
bytes: An "annotated tag" i...
mandoc: gitcore-tutorial.7:682:225: STYLE: input text line longer than 80
bytes: which will sign the ...
mandoc: gitcore-tutorial.7:684:310: STYLE: input text line longer than 80
bytes: You normally only do...
mandoc: gitcore-tutorial.7:686:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:687:348: STYLE: input text line longer than 80
bytes: Git repositories are...
mandoc: gitcore-tutorial.7:697:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:699:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:701:403: STYLE: input text line longer than 80
bytes: You can tell Git to ...
mandoc: gitcore-tutorial.7:715:139: STYLE: input text line longer than 80
bytes: if you grow bored wi...
mandoc: gitcore-tutorial.7:727:118: STYLE: input text line longer than 80
bytes: and it will be gone\...
mandoc: gitcore-tutorial.7:740:160: STYLE: input text line longer than 80
bytes: command, but if all ...
mandoc: gitcore-tutorial.7:743:230: STYLE: input text line longer than 80
bytes: Note that when you\(...
mandoc: gitcore-tutorial.7:760:185: STYLE: input text line longer than 80
bytes: Note that the second...
mandoc: gitcore-tutorial.7:762:364: STYLE: input text line longer than 80
bytes: When copying a remot...
mandoc: gitcore-tutorial.7:776:397: STYLE: input text line longer than 80
bytes: which will force a t...
mandoc: gitcore-tutorial.7:791:402: STYLE: input text line longer than 80
bytes: and in fact a lot of...
mandoc: gitcore-tutorial.7:793:299: STYLE: input text line longer than 80
bytes: Many (most?) public ...
mandoc: gitcore-tutorial.7:795:290: STYLE: input text line longer than 80
bytes: To create your own l...
mandoc: gitcore-tutorial.7:823:247: STYLE: input text line longer than 80
bytes: to populate the inde...
mandoc: gitcore-tutorial.7:836:391: STYLE: input text line longer than 80
bytes: where the \fB\-u\fR ...
mandoc: gitcore-tutorial.7:855:99: STYLE: input text line longer than 80 bytes:
You have now success...
mandoc: gitcore-tutorial.7:857:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:858:242: STYLE: input text line longer than 80
bytes: Branches in Git are ...
mandoc: gitcore-tutorial.7:860:393: STYLE: input text line longer than 80
bytes: You can at any time ...
mandoc: gitcore-tutorial.7:862:197: STYLE: input text line longer than 80
bytes: To show that as an e...
mandoc: gitcore-tutorial.7:875:86: STYLE: input text line longer than 80 bytes:
will create a new br...
mandoc: gitcore-tutorial.7:885:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:887:2: WARNING: skipping paragraph macro: br after br
mandoc: gitcore-tutorial.7:889:273: STYLE: input text line longer than 80
bytes: If you make the deci...
mandoc: gitcore-tutorial.7:902:112: STYLE: input text line longer than 80
bytes: and it would create ...
mandoc: gitcore-tutorial.7:919:105: STYLE: input text line longer than 80
bytes: (or any other branch...
mandoc: gitcore-tutorial.7:932:89: STYLE: input text line longer than 80 bytes:
will tell you where ...
mandoc: gitcore-tutorial.7:945:160: STYLE: input text line longer than 80
bytes: which used to be not...
mandoc: gitcore-tutorial.7:947:135: STYLE: input text line longer than 80
bytes: Sometimes you may wi...
mandoc: gitcore-tutorial.7:960:265: STYLE: input text line longer than 80
bytes: which will simply \f...
mandoc: gitcore-tutorial.7:962:2: WARNING: skipping paragraph macro: sp after SH
mandoc: gitcore-tutorial.7:963:330: STYLE: input text line longer than 80
bytes: One of the ideas of ...
mandoc: gitcore-tutorial.7:978:424: STYLE: input text line longer than 80
bytes: Here, we just added ...
mandoc: gitcore-tutorial.7:980:212: STYLE: input text line longer than 80
bytes: Now, to make it a bi...
mandoc: gitcore-tutorial.7:993:222: STYLE: input text line longer than 80
bytes: Here, take a moment ...
mandoc: gitcore-tutorial.7:1010:187: STYLE: input text line longer than 80
bytes: Now, you\(cqve got t...
mandoc: gitcore-tutorial.7:1023:236: STYLE: input text line longer than 80
bytes: will show you graphi...
mandoc: gitcore-tutorial.7:1025:360: STYLE: input text line longer than 80
bytes: Anyway, let\(cqs exi...
mandoc: gitcore-tutorial.7:1038:112: STYLE: input text line longer than 80
bytes: where the first argu...
mandoc: gitcore-tutorial.7:1040:294: STYLE: input text line longer than 80
bytes: Now, in this case we...
mandoc: gitcore-tutorial.7:1055:94: STYLE: input text line longer than 80
bytes: It tells you that it...
mandoc: gitcore-tutorial.7:1057:313: STYLE: input text line longer than 80
bytes: Not to worry\&. It l...
mandoc: gitcore-tutorial.7:1086:194: STYLE: input text line longer than 80
bytes: which will very loud...
mandoc: gitcore-tutorial.7:1088:411: STYLE: input text line longer than 80
bytes: After you\(cqre done...
mandoc: gitcore-tutorial.7:1090:112: STYLE: input text line longer than 80
bytes: Another useful tool,...
mandoc: gitcore-tutorial.7:1109:1118: STYLE: input text line longer than 80
bytes: The first two lines ...
mandoc: gitcore-tutorial.7:1119:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1121:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1123:251: STYLE: input text line longer than 80
bytes: Without the \fI\-\-m...
mandoc: gitcore-tutorial.7:1135:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1137:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1139:252: STYLE: input text line longer than 80
bytes: If there were more c...
mandoc: gitcore-tutorial.7:1143:276: STYLE: input text line longer than 80
bytes: Now, let\(cqs preten...
mandoc: gitcore-tutorial.7:1157:84: STYLE: input text line longer than 80
bytes: This outputs somethi...
mandoc: gitcore-tutorial.7:1174:312: STYLE: input text line longer than 80
bytes: Because your branch ...
mandoc: gitcore-tutorial.7:1176:130: STYLE: input text line longer than 80
bytes: You can run \fBgitk ...
mandoc: gitcore-tutorial.7:1193:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1194:392: STYLE: input text line longer than 80
bytes: It\(cqs usually much...
mandoc: gitcore-tutorial.7:1209:84: STYLE: input text line longer than 80
bytes: One of the following...
mandoc: gitcore-tutorial.7:1218:112: STYLE: input text line longer than 80
bytes: This transport can b...
mandoc: gitcore-tutorial.7:1220:258: STYLE: input text line longer than 80
bytes: to the remote machin...
mandoc: gitcore-tutorial.7:1229:92: STYLE: input text line longer than 80
bytes: to run both ends on ...
mandoc: gitcore-tutorial.7:1237:185: STYLE: input text line longer than 80
bytes: This transport was d...
mandoc: gitcore-tutorial.7:1244:142: STYLE: input text line longer than 80
bytes: Downloader from http...
mandoc: gitcore-tutorial.7:1248:264: STYLE: input text line longer than 80
bytes: using the object nam...
mandoc: gitcore-tutorial.7:1259:91: STYLE: input text line longer than 80
bytes: Once you fetch from ...
mandoc: gitcore-tutorial.7:1261:147: STYLE: input text line longer than 80
bytes: However \(em it\(cqs...
mandoc: gitcore-tutorial.7:1284:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1286:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1288:549: STYLE: input text line longer than 80
bytes: You could do without...
mandoc: gitcore-tutorial.7:1292:199: STYLE: input text line longer than 80
bytes: It is likely that yo...
mandoc: gitcore-tutorial.7:1355:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1356:305: STYLE: input text line longer than 80
bytes: We said this tutoria...
mandoc: gitcore-tutorial.7:1358:178: STYLE: input text line longer than 80
bytes: OK, still with me? T...
mandoc: gitcore-tutorial.7:1377:154: STYLE: input text line longer than 80
bytes: Remember, before run...
mandoc: gitcore-tutorial.7:1426:283: STYLE: input text line longer than 80
bytes: The command writes t...
mandoc: gitcore-tutorial.7:1453:626: STYLE: input text line longer than 80
bytes: This is the same \fI...
mandoc: gitcore-tutorial.7:1455:170: STYLE: input text line longer than 80
bytes: After \fIcollapsing\...
mandoc: gitcore-tutorial.7:1472:346: STYLE: input text line longer than 80
bytes: In our example of on...
mandoc: gitcore-tutorial.7:1490:209: STYLE: input text line longer than 80
bytes: The next step of mer...
mandoc: gitcore-tutorial.7:1523:318: STYLE: input text line longer than 80
bytes: This is the state of...
mandoc: gitcore-tutorial.7:1525:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1526:141: STYLE: input text line longer than 80
bytes: So, we can use someb...
mandoc: gitcore-tutorial.7:1528:521: STYLE: input text line longer than 80
bytes: You do your real wor...
mandoc: gitcore-tutorial.7:1538:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1540:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1542:119: STYLE: input text line longer than 80
bytes: This public reposito...
mandoc: gitcore-tutorial.7:1546:237: STYLE: input text line longer than 80
bytes: Publishing the chang...
mandoc: gitcore-tutorial.7:1548:266: STYLE: input text line longer than 80
bytes: First, you need to c...
mandoc: gitcore-tutorial.7:1558:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1560:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1566:303: STYLE: input text line longer than 80
bytes: Your private reposit...
mandoc: gitcore-tutorial.7:1579:170: STYLE: input text line longer than 80
bytes: Then, make that dire...
mandoc: gitcore-tutorial.7:1592:219: STYLE: input text line longer than 80
bytes: Make sure this direc...
mandoc: gitcore-tutorial.7:1602:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1604:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1606:342: STYLE: input text line longer than 80
bytes: Many installations o...
mandoc: gitcore-tutorial.7:1618:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1620:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1622:283: STYLE: input text line longer than 80
bytes: If you plan to publi...
mandoc: gitcore-tutorial.7:1626:154: STYLE: input text line longer than 80
bytes: Your "public reposit...
mandoc: gitcore-tutorial.7:1639:170: STYLE: input text line longer than 80
bytes: This synchronizes yo...
mandoc: gitcore-tutorial.7:1641:161: STYLE: input text line longer than 80
bytes: As a real example, t...
mandoc: gitcore-tutorial.7:1654:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1655:371: STYLE: input text line longer than 80
bytes: Earlier, we saw that...
mandoc: gitcore-tutorial.7:1668:282: STYLE: input text line longer than 80
bytes: will do it for you\&...
mandoc: gitcore-tutorial.7:1678:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1680:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1682:391: STYLE: input text line longer than 80
bytes: You will see two fil...
mandoc: gitcore-tutorial.7:1686:169: STYLE: input text line longer than 80
bytes: If you are paranoid,...
mandoc: gitcore-tutorial.7:1688:122: STYLE: input text line longer than 80
bytes: Once you have packed...
mandoc: gitcore-tutorial.7:1703:260: STYLE: input text line longer than 80
bytes: You can try running ...
mandoc: gitcore-tutorial.7:1713:2: WARNING: skipping paragraph macro: br before
sp
mandoc: gitcore-tutorial.7:1715:2: WARNING: skipping paragraph macro: br after
br
mandoc: gitcore-tutorial.7:1721:505: STYLE: input text line longer than 80
bytes: If you run \fBgit re...
mandoc: gitcore-tutorial.7:1723:313: STYLE: input text line longer than 80
bytes: When a repository is...
mandoc: gitcore-tutorial.7:1725:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1726:312: STYLE: input text line longer than 80
bytes: Although Git is a tr...
mandoc: gitcore-tutorial.7:1728:230: STYLE: input text line longer than 80
bytes: It should be stresse...
mandoc: gitcore-tutorial.7:1740:83: STYLE: input text line longer than 80
bytes: Prepare your primary...
mandoc: gitcore-tutorial.7:1753:119: STYLE: input text line longer than 80
bytes: If other people are ...
mandoc: gitcore-tutorial.7:1785:123: STYLE: input text line longer than 80
bytes: the public repositor...
mandoc: gitcore-tutorial.7:1787:86: STYLE: input text line longer than 80
bytes: if the transport use...
mandoc: gitcore-tutorial.7:1798:219: STYLE: input text line longer than 80
bytes: Keep working in your...
mandoc: gitcore-tutorial.7:1827:130: STYLE: input text line longer than 80
bytes: A recommended work c...
mandoc: gitcore-tutorial.7:1839:151: STYLE: input text line longer than 80
bytes: on the public reposi...
mandoc: gitcore-tutorial.7:1850:93: STYLE: input text line longer than 80
bytes: Prepare a public rep...
mandoc: gitcore-tutorial.7:1861:198: STYLE: input text line longer than 80
bytes: Copy over the packed...
mandoc: gitcore-tutorial.7:1877:86: STYLE: input text line longer than 80
bytes: if the transport use...
mandoc: gitcore-tutorial.7:1888:257: STYLE: input text line longer than 80
bytes: Keep working in your...
mandoc: gitcore-tutorial.7:1901:138: STYLE: input text line longer than 80
bytes: Push your changes to...
mandoc: gitcore-tutorial.7:1917:138: STYLE: input text line longer than 80
bytes: A recommended work c...
mandoc: gitcore-tutorial.7:1929:206: STYLE: input text line longer than 80
bytes: the public repositor...
mandoc: gitcore-tutorial.7:1955:101: STYLE: input text line longer than 80
bytes: from the public repo...
mandoc: gitcore-tutorial.7:1986:114: STYLE: input text line longer than 80
bytes: to prepare patches f...
mandoc: gitcore-tutorial.7:1989:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1990:260: STYLE: input text line longer than 80
bytes: If you are coming fr...
mandoc: gitcore-tutorial.7:1994:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:1995:160: STYLE: input text line longer than 80
bytes: It is likely that yo...
mandoc: gitcore-tutorial.7:1997:329: STYLE: input text line longer than 80
bytes: We have already seen...
mandoc: gitcore-tutorial.7:2019:168: STYLE: input text line longer than 80
bytes: Both fixes are teste...
mandoc: gitcore-tutorial.7:2057:448: STYLE: input text line longer than 80
bytes: However, there is no...
mandoc: gitcore-tutorial.7:2070:254: STYLE: input text line longer than 80
bytes: You can make sure \f...
mandoc: gitcore-tutorial.7:2094:660: STYLE: input text line longer than 80
bytes: Note that you should...
mandoc: gitcore-tutorial.7:2096:2: WARNING: skipping paragraph macro: sp after
SH
mandoc: gitcore-tutorial.7:2099:2: WARNING: skipping paragraph macro: sp after
SH
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
2110
\%https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
60:.sp .5v
165:.sp .5v
181:.sp .5v
317:.sp .5v
333:.sp .5v
524:.sp .5v
631:.sp .5v
702:.sp .5v
903:.sp .5v
1124:.sp .5v
1140:.sp .5v
1289:.sp .5v
1543:.sp .5v
1563:.sp .5v
1607:.sp .5v
1623:.sp .5v
1683:.sp .5v
1718:.sp .5v
-.-.
Show if docman-to-man created this
3:.\" Author: [FIXME: author] [see
http://www.docbook.org/tdg5/en/html/author]
4:.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':2110
troff:<stdin>:2110: warning: [page 21, 7.3i]: cannot break line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':2110
troff:<stdin>:2110: warning: [page 22, line 47]: cannot break line
-.-.
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them as
such and not as an end of sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
--- gitcore-tutorial.7 2024-09-24 21:31:58.218881293 +0000
+++ gitcore-tutorial.7.new 2024-09-24 22:07:51.484944926 +0000
@@ -30,10 +30,8 @@
.SH "NAME"
gitcore-tutorial \- A Git core tutorial for developers
.SH "SYNOPSIS"
-.sp
git *
.SH "DESCRIPTION"
-.sp
This tutorial explains how to use the "core" Git commands to set up and work
with a Git repository\&.
.sp
If you just need to use Git as a revision control system you may prefer to
start with "A Tutorial Introduction to Git" (\fBgittutorial\fR(7)) or
\m[blue]\fBthe Git User Manual\fR\m[]\&\s-2\u[1]\d\s+2\&.
@@ -57,10 +55,9 @@ Back when this document was originally w
.br
.sp
Deeper technical details are often marked as Notes, which you can skip on your
first reading\&.
-.sp .5v
+.sp 0.5v
.RE
.SH "CREATING A GIT REPOSITORY"
-.sp
Creating a new Git repository couldn\(cqt be easier: all Git repositories
start out empty, and the only thing you need to do is find yourself a
subdirectory that you want to use as a working tree \- either an empty one for
a totally new project, or an existing working tree that you want to import into
Git\&.
.sp
For our first example, we\(cqre going to start a totally new repository from
scratch, with no pre\-existing files, and we\(cqll call it
\fIgit\-tutorial\fR\&. To start up, create a subdirectory for it, change into
that subdirectory, and initialize the Git infrastructure with \fIgit init\fR:
@@ -162,7 +159,7 @@ However, this is only a convention, and
.br
.sp
An \fIobject\fR is identified by its 160\-bit SHA\-1 hash, aka \fIobject
name\fR, and a reference to an object is always the 40\-byte hex representation
of that SHA\-1 name\&. The files in the \fBrefs\fR subdirectory are expected to
contain these hex references (usually with a final \fB\en\fR at the end), and
you should thus expect to see a number of 41\-byte files containing these
references in these \fBrefs\fR subdirectories when you actually start
populating your tree\&.
-.sp .5v
+.sp 0.5v
.RE
.if n \{\
.sp
@@ -175,15 +172,13 @@ An \fIobject\fR is identified by its 160
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
An advanced user may want to take a look at \fBgitrepository-layout\fR(5)
after finishing this tutorial\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
You have now created your first Git repository\&. Of course, since it\(cqs
empty, that\(cqs not very useful, so let\(cqs start populating it with data\&.
.SH "POPULATING A GIT REPOSITORY"
-.sp
We\(cqll keep this simple and stupid, so we\(cqll start off with populating a
few trivial files just to get a feel for it\&.
.sp
Start off with just creating any random files that you want to maintain in
your Git repository\&. We\(cqll start off with a few bad examples, just to get
a feel for how this works:
@@ -311,10 +306,9 @@ which will print out "Hello World"\&. Th
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
Don\(cqt confuse that object with the file \fBhello\fR itself\&. The object is
literally just those specific \fBcontents\fR of the file, and however much you
later change the contents in file \fBhello\fR, the object we just looked at
will never change\&. Objects are immutable\&.
-.sp .5v
+.sp 0.5v
.RE
.if n \{\
.sp
@@ -327,10 +321,9 @@ Don\(cqt confuse that object with the fi
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
The second example demonstrates that you can abbreviate the object name to
only the first several hexadecimal digits in most places\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
Anyway, as we mentioned previously, you normally never actually take a look at
the objects themselves, and typing long 40\-character hex names is not
something you\(cqd normally want to do\&. The above digression was just to show
that \fIgit update\-index\fR did something magical, and actually saved away the
contents of your files into the Git object database\&.
@@ -411,7 +404,6 @@ index 557db03\&.\&.263414f 100644
.\}
.sp
.SH "COMMITTING GIT STATE"
-.sp
Now, we want to go to the next stage in Git, which is to take the files that
Git knows about in the index, and commit them as a real tree\&. We do that in
two phases: creating a \fItree\fR object, and committing that \fItree\fR object
as a \fIcommit\fR object together with an explanation of what the tree was all
about, along with information of how we came to that state\&.
.sp
Creating a tree object is trivial, and is done with \fIgit write\-tree\fR\&.
There are no options or other input: \fBgit write\-tree\fR will take the
current index state, and write an object that describes that whole index\&. In
other words, we\(cqre now tying together all the different filenames with their
contents (and their permissions), and we\(cqre creating the equivalent of a Git
"directory" object:
@@ -465,7 +457,6 @@ In this case this creates a totally new
.sp
Again, normally you\(cqd never actually do this by hand\&. There is a helpful
script called \fBgit commit\fR that will do all of this for you\&. So you could
have just written \fBgit commit\fR instead, and it would have done the above
magic scripting for you\&.
.SH "MAKING A CHANGE"
-.sp
Remember how we did the \fIgit update\-index\fR on file \fBhello\fR and then
we changed \fBhello\fR afterward, and could compare the new state of
\fBhello\fR with the state we saved in the index file?
.sp
Further, remember how I said that \fIgit write\-tree\fR writes the contents of
the \fBindex\fR file to the tree, and thus what we just committed was in fact
the \fBoriginal\fR contents of the file \fBhello\fR, not the new ones\&. We did
that on purpose, to show the difference between the index state, and the state
in the working tree, and how they don\(cqt have to match, even when we commit
things\&.
@@ -516,12 +507,11 @@ In other words, \fIgit diff\-index\fR no
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
\fIgit diff\-index\fR really always uses the index for its comparisons, and
saying that it compares a tree against the working tree is thus not strictly
accurate\&. In particular, the list of files to compare (the "meta\-data")
\fBalways\fR comes from the index file, regardless of whether the
\fB\-\-cached\fR flag is used or not\&. The \fB\-\-cached\fR flag really only
determines whether the file \fBcontents\fR to be compared come from the working
tree or not\&.
.sp
This is not hard to understand, as soon as you realize that Git simply never
knows (or cares) about files that it is not told about explicitly\&. Git will
never go \fBlooking\fR for files to compare, it expects you to tell it what the
files are, and that\(cqs what the index is there for\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
However, our next step is to commit the \fBchange\fR we did, and again, to
understand what\(cqs going on, keep in mind the difference between "working
tree contents", "index file" and "committed tree"\&. We have changes in the
working tree that we want to commit, and we always have to work through the
index file, so the first thing we need to do is to update the index cache:
@@ -560,7 +550,6 @@ Write whatever message you want, and all
.sp
You\(cqve now made your first real Git commit\&. And if you\(cqre interested
in looking at what \fBgit commit\fR really does, feel free to investigate:
it\(cqs a few very simple shell scripts to generate the helpful (?) commit
message headers, and a few one\-liners that actually do the commit itself
(\fIgit commit\fR)\&.
.SH "INSPECTING CHANGES"
-.sp
While creating changes is useful, it\(cqs even more useful if you can tell
later what changed\&. The most useful command for this is another of the
\fIdiff\fR family, namely \fIgit diff\-tree\fR\&.
.sp
\fIgit diff\-tree\fR can be given two arbitrary trees, and it will tell you
the differences between them\&. Perhaps even more commonly, though, you can
give it just a single commit object, and it will figure out the parent of that
commit itself, and show the difference directly\&. Thus, to get the same diff
that we\(cqve already seen several times, we can now do
@@ -588,7 +577,6 @@ $ git diff\-tree \-p HEAD
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
Here is an ASCII art by Jon Loeliger that illustrates how various
\fIdiff\-*\fR commands compare things\&.
.sp
@@ -628,14 +616,13 @@ diff\-index | V
.if n \{\
.RE
.\}
-.sp .5v
+.sp 0.5v
.RE
.sp
More interestingly, you can also give \fIgit diff\-tree\fR the
\fB\-\-pretty\fR flag, which tells it to also show the commit message and
author and date of the commit, and you can tell it to show a whole series of
diffs\&. Alternatively, you can tell it to be "silent", and not show the diffs
at all, but just show the actual commit message\&.
.sp
In fact, together with the \fIgit rev\-list\fR program (which generates a list
of revisions), \fIgit diff\-tree\fR ends up being a veritable fount of
changes\&. You can emulate \fBgit log\fR, \fBgit log \-p\fR, etc\&. with a
trivial script that pipes the output of \fBgit rev\-list\fR to \fBgit
diff\-tree \-\-stdin\fR, which was exactly how early versions of \fBgit log\fR
were implemented\&.
.SH "TAGGING A VERSION"
-.sp
In Git, there are two kinds of tags, a "light" one, and an "annotated tag"\&.
.sp
A "light" tag is technically nothing more than a branch, except we put it in
the \fB\&.git/refs/tags/\fR subdirectory instead of calling it a \fBhead\fR\&.
So the simplest form of tag involves nothing more than
@@ -683,7 +670,6 @@ which will sign the current \fBHEAD\fR (
.sp
You normally only do signed tags for major releases or things like that, while
the light\-weight tags are useful for any marking you want to do \(em any time
you decide that you want to remember a certain point, just create a private tag
for it, and you have a nice symbolic name for the state at that point\&.
.SH "COPYING REPOSITORIES"
-.sp
Git repositories are normally totally self\-sufficient and relocatable\&.
Unlike CVS, for example, there is no separate notion of "repository" and
"working tree"\&. A Git repository normally \fBis\fR the working tree, with the
local Git information hidden in the \fB\&.git\fR subdirectory\&. There is
nothing else\&. What you see is what you got\&.
.if n \{\
.sp
@@ -696,10 +682,9 @@ Git repositories are normally totally se
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
You can tell Git to split the Git internal information from the directory that
it tracks, but we\(cqll ignore that for now: it\(cqs not how normal projects
work, and it\(cqs really only meant for special uses\&. So the mental model of
"the Git information is always tied directly to the working tree that it
describes" may not be technically 100% accurate, but it\(cqs a good model for
all normal use\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
This has two implications:
@@ -854,7 +839,6 @@ which will end up doing all of the above
.sp
You have now successfully copied somebody else\(cqs (mine) remote repository,
and checked it out\&.
.SH "CREATING A NEW BRANCH"
-.sp
Branches in Git are really nothing more than pointers into the Git object
database from within the \fB\&.git/refs/\fR subdirectory, and as we already
discussed, the \fBHEAD\fR branch is nothing but a symlink to one of these
object pointers\&.
.sp
You can at any time create a new branch by just picking an arbitrary point in
the project history, and just writing the SHA\-1 name of that object into a
file under \fB\&.git/refs/heads/\fR\&. You can use any filename you want (and
indeed, subdirectories), but the convention is that the "normal" branch is
called \fBmaster\fR\&. That\(cqs just a convention, though, and nothing
enforces it\&.
@@ -884,7 +868,6 @@ will create a new branch based at the cu
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
If you make the decision to start your new branch at some other point in the
history than the current \fBHEAD\fR, you can do so by just telling \fIgit
switch\fR what the base of the checkout would be\&. In other words, if you have
an earlier tag or branch, you\(cqd just do
.sp
@@ -900,7 +883,7 @@ $ git switch \-c mybranch earlier\-commi
.sp
.sp
and it would create the new branch \fBmybranch\fR at the earlier commit, and
check out the state at that time\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
You can always just jump back to your original \fBmaster\fR branch by doing
@@ -959,7 +942,6 @@ $ git branch <branchname> [startingpoint
.sp
which will simply \fIcreate\fR the branch, but will not do anything further\&.
You can then later \(em once you decide that you want to actually develop on
that branch \(em switch to that branch with a regular \fIgit switch\fR with the
branchname as the argument\&.
.SH "MERGING TWO BRANCHES"
-.sp
One of the ideas of having a branch is that you do some (possibly
experimental) work in it, and eventually merge it back to the main branch\&. So
assuming you created the above \fBmybranch\fR that started out being the same
as the original \fBmaster\fR branch, let\(cqs make sure we\(cqre in that
branch, and do some work there\&.
.sp
.if n \{\
@@ -1118,10 +1100,9 @@ The first two lines indicate that it is
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
Without the \fI\-\-more=1\fR option, \fIgit show\-branch\fR would not output
the \fI[master^]\fR commit, as \fI[mybranch]\fR commit is a common ancestor of
both \fImaster\fR and \fImybranch\fR tips\&. Please see
\fBgit-show-branch\fR(1) for details\&.
-.sp .5v
+.sp 0.5v
.RE
.if n \{\
.sp
@@ -1134,10 +1115,9 @@ Without the \fI\-\-more=1\fR option, \fI
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
If there were more commits on the \fImaster\fR branch after the merge, the
merge commit itself would not be shown by \fIgit show\-branch\fR by default\&.
You would need to provide \fB\-\-sparse\fR option to make the merge commit
visible in this case\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
Now, let\(cqs pretend you are the one who did all the work in \fBmybranch\fR,
and the fruit of your hard work has finally been merged to the \fBmaster\fR
branch\&. Let\(cqs go back to \fBmybranch\fR, and run \fIgit merge\fR to get
the "upstream changes" back to your branch\&.
@@ -1190,7 +1170,6 @@ $ git show\-branch master mybranch
.\}
.sp
.SH "MERGING EXTERNAL WORK"
-.sp
It\(cqs usually much more common that you merge with somebody else than
merging with your own branches, so it\(cqs worth pointing out that Git makes
that very easy too, and in fact, it\(cqs not that different from doing a \fIgit
merge\fR\&. In fact, a remote merge ends up being nothing more than "fetch the
work from a remote repository into a temporary tag" followed by a \fIgit
merge\fR\&.
.sp
Fetching from a remote repository is done by, unsurprisingly, \fIgit fetch\fR:
@@ -1283,10 +1262,9 @@ and optionally give a branch\-name for t
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
You could do without using any branches at all, by keeping as many local
repositories as you would like to have branches, and merging between them with
\fIgit pull\fR, just like you merge between branches\&. The advantage of this
approach is that it lets you keep a set of files for each \fBbranch\fR checked
out and you may find it easier to switch back and forth if you juggle multiple
lines of development simultaneously\&. Of course, you will pay the price of
more disk usage to hold multiple working trees, but disk space is cheap these
days\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
It is likely that you will be pulling from the same remote repository from
time to time\&. As a short hand, you can store the remote repository URL in the
local repository\(cqs config file like this:
@@ -1352,7 +1330,6 @@ the above are equivalent to:
\fBgit pull http://www\&.kernel\&.org/pub/scm/git/git\&.git/ tag v0\&.99\&.1\fR
.RE
.SH "HOW DOES THE MERGE WORK?"
-.sp
We said this tutorial shows what plumbing does to help you cope with the
porcelain that isn\(cqt flushing, but we so far did not talk about how the
merge really works\&. If you are following this tutorial the first time, I\(cqd
suggest to skip to "Publishing your work" section and come back here later\&.
.sp
OK, still with me? To give us an example to look at, let\(cqs go back to the
earlier repository with "hello" and "example" file, and bring ourselves back to
the pre\-merge state:
@@ -1522,7 +1499,6 @@ $ git ls\-files \-\-stage
.sp
This is the state of the index file and the working file after \fIgit merge\fR
returns control back to you, leaving the conflicting merge for you to
resolve\&. Notice that the path \fBhello\fR is still unmerged, and what you see
with \fIgit diff\fR at this point is differences since stage 2 (i\&.e\&. your
version)\&.
.SH "PUBLISHING YOUR WORK"
-.sp
So, we can use somebody else\(cqs work from a remote repository, but how can
\fByou\fR prepare a repository to let other people pull from it?
.sp
You do your real work in your working tree that has your primary repository
hanging under it as its \fB\&.git\fR subdirectory\&. You \fBcould\fR make that
repository accessible remotely and ask people to pull from it, but in practice
that is not the way things are usually done\&. A recommended way is to have a
public repository, make it reachable by other people, and when the changes you
made in your primary working tree are in good shape, update the public
repository from it\&. This is often called \fIpushing\fR\&.
@@ -1537,10 +1513,9 @@ You do your real work in your working tr
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
This public repository could further be mirrored, and that is how Git
repositories at \fBkernel\&.org\fR are managed\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
Publishing the changes from your local (private) repository to your remote
(public) repository requires a write privilege on the remote machine\&. You
need to have an SSH account there to run a single command,
\fIgit\-receive\-pack\fR\&.
@@ -1557,10 +1532,9 @@ First, you need to create an empty repos
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
\fIgit push\fR uses a pair of commands, \fIgit send\-pack\fR on your local
machine, and \fIgit\-receive\-pack\fR on the remote machine\&. The
communication between the two over the network internally uses an SSH
connection\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
Your private repository\(cqs Git directory is usually \fB\&.git\fR, but your
public repository is often named after the project name, i\&.e\&.
\fB<project>\&.git\fR\&. Let\(cqs create such a public repository for project
\fBmy\-git\fR\&. After logging into the remote machine, create an empty
directory:
@@ -1601,10 +1575,9 @@ Make sure this directory is available fo
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
Many installations of sshd do not invoke your shell as the login shell when
you directly run programs; what this means is that if your login shell is
\fIbash\fR, only \fB\&.bashrc\fR is read and not \fB\&.bash_profile\fR\&. As a
workaround, make sure \fB\&.bashrc\fR sets up \fB$PATH\fR so that you can run
\fIgit\-receive\-pack\fR program\&.
-.sp .5v
+.sp 0.5v
.RE
.if n \{\
.sp
@@ -1617,10 +1590,9 @@ Many installations of sshd do not invoke
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
If you plan to publish this repository to be accessed over http, you should do
\fBmv my\-git\&.git/hooks/post\-update\&.sample
my\-git\&.git/hooks/post\-update\fR at this point\&. This makes sure that every
time you push into this repository, \fBgit update\-server\-info\fR is run\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
Your "public repository" is now ready to accept your changes\&. Come back to
the machine you have your private repository\&. From there, run this command:
@@ -1651,7 +1623,6 @@ $ git push master\&.kernel\&.org:/pub/sc
.\}
.sp
.SH "PACKING YOUR REPOSITORY"
-.sp
Earlier, we saw that one file under \fB\&.git/objects/??/\fR directory is
stored for each Git object you create\&. This representation is efficient to
create atomically and safely, but not so convenient to transport over the
network\&. Since Git objects are immutable once they are created, there is a
way to optimize the storage by "packing them together"\&. The command
.sp
.if n \{\
@@ -1677,10 +1648,9 @@ will do it for you\&. If you followed th
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
You will see two files, \fBpack\-*\&.pack\fR and \fBpack\-*\&.idx\fR, in
\fB\&.git/objects/pack\fR directory\&. They are closely related to each other,
and if you ever copy them by hand to a different repository for whatever
reason, you should make sure you copy them together\&. The former holds all the
data from the objects in the pack, and the latter holds the index for random
access\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
If you are paranoid, running \fIgit verify\-pack\fR command would detect if
you have a corrupt pack, but do not worry too much\&. Our programs are always
perfect ;\-)\&.
@@ -1712,17 +1682,15 @@ You can try running \fBfind \&.git/objec
.ps +1
\fBNote\fR
.ps -1
-.br
.sp
\fBgit pull\fR is slightly cumbersome for HTTP transport, as a packed
repository may contain relatively few objects in a relatively large pack\&. If
you expect many HTTP pulls from your public repository you might want to repack
& prune often, or never\&.
-.sp .5v
+.sp 0.5v
.RE
.sp
If you run \fBgit repack\fR again at this point, it will say "Nothing new to
pack\&."\&. Once you continue your development and accumulate the changes,
running \fBgit repack\fR again will create a new pack, that contains objects
created since you packed your repository the last time\&. We recommend that you
pack your project soon after the initial import (unless you are starting your
project from scratch), and then run \fBgit repack\fR every once in a while,
depending on how active your project is\&.
.sp
When a repository is synchronized via \fBgit push\fR and \fBgit pull\fR
objects packed in the source repository are usually stored unpacked in the
destination\&. While this allows you to use different packing strategies on
both ends, it also means you may need to repack both repositories every once in
a while\&.
.SH "WORKING WITH OTHERS"
-.sp
Although Git is a truly distributed system, it is often convenient to organize
your project with an informal hierarchy of developers\&. Linux kernel
development is run this way\&. There is a nice illustration (page 17, "Merges
to Mainline") in \m[blue]\fBRandy Dunlap\(cqs
presentation\fR\m[]\&\s-2\u[2]\d\s+2\&.
.sp
It should be stressed that this hierarchy is purely \fBinformal\fR\&. There is
nothing fundamental in Git that enforces the "chain of patch flow" this
hierarchy implies\&. You do not have to pull from only one remote repository\&.
@@ -1986,12 +1954,10 @@ Use
to prepare patches for e\-mail submission to your upstream and send it out\&.
Go back to step 2\&. and continue\&.
.RE
.SH "WORKING WITH OTHERS, SHARED REPOSITORY STYLE"
-.sp
If you are coming from a CVS background, the style of cooperation suggested in
the previous section may be new to you\&. You do not have to worry\&. Git
supports the "shared public repository" style of cooperation you are probably
more familiar with as well\&.
.sp
See \fBgitcvs-migration\fR(7) for the details\&.
.SH "BUNDLING YOUR WORK TOGETHER"
-.sp
It is likely that you will be working on more than one thing at a time\&. It
is easy to manage those more\-or\-less independent tasks using branches with
Git\&.
.sp
We have already seen how branches work previously, with "fun and work" example
using two branches\&. The idea is the same if there are more than two
branches\&. Let\(cqs say you started out from "master" head, and have some new
code in the "master" branch, and two independent fixes in the "commit\-fix" and
"diff\-fix" branches:
@@ -2093,10 +2059,8 @@ $ git show\-branch
.sp
Note that you should not do Octopus just because you can\&. An octopus is a
valid thing to do and often makes it easier to view the commit history if you
are merging more than two independent changes at the same time\&. However, if
you have merge conflicts with any of the branches you are merging in and need
to hand resolve, that is an indication that the development happened in those
branches were not independent after all, and you should merge two at a time,
documenting how you resolved the conflicts, and the reason why you preferred
changes made in one side over the other\&. Otherwise it would make the project
history harder to follow, not easier\&.
.SH "SEE ALSO"
-.sp
\fBgittutorial\fR(7), \fBgittutorial-2\fR(7), \fBgitcvs-migration\fR(7),
\fBgit-help\fR(1), \fBgiteveryday\fR(7), \m[blue]\fBThe Git User\(cqs
Manual\fR\m[]\&\s-2\u[1]\d\s+2
.SH "GIT"
-.sp
Part of the \fBgit\fR(1) suite
.SH "NOTES"
.IP " 1." 4
@@ -2107,5 +2071,5 @@ the Git User Manual
.IP " 2." 4
Randy Dunlap\(cqs presentation
.RS 4
-\%https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf
+\%https://web.archive.org/\:web/20120915203609/\:http://www.xenotime.net/\:linux/mentor/\:linux\-mentoring\-2006.pdf
.RE
