summaryrefslogtreecommitdiff
path: root/Documentation/user-manual.txt
AgeCommit message (Collapse)AuthorFilesLines
2019-09-28user-manual.txt: render ASCII art correctly under AsciidoctorLibravatar Martin Ågren1-9/+11
This commit is similar to 379805051d ("Documentation: render revisions correctly under Asciidoctor", 2018-05-06) and is a no-op with AsciiDoc. When creating a literal block from an indented block without any sort of delimiters, Asciidoctor strips off all leading whitespace, resulting in a misrendered ASCII drawing. Use an explicit literal block to indicate to Asciidoctor that we want to keep the leading whitespace. Drop the common indentation for all lines to make this a no-op with AsciiDoc. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-28user-manual.txt: change header notationLibravatar Martin Ågren1-236/+120
When AsciiDoc processes user-manual.txt, it generates a book containing chapters containing sections. So for example, we have chapter 6, "Advanced branch management", which contains four relatively short sections, 6.1-6.4. Asciidoctor generates a book containing *parts* containing *chapters* instead. So part 6, "Advanced branch management" contains four short chapters, 1-4. This looks a bit odd. To make AsciiDoc (8.6.10) and Asciidoctor (1.5.5) handle these the same, change from indicating chapters like so: [[foobar]] Foobar ====== to doing it like so: [[foobar]] == Foobar Same thing for sections (line of dashes to ===), subsections (line of tildes to ====) and subsubsections (line of carets to =====). Mark the appendices with "[appendix]", which both AsciiDoc and Asciidoctor understand. This means we need to drop the "Appendix X: " from their titles, or those "Appendix X: " would be included literally in the name of the appendix. This commit is a no-op for AsciiDoc: The generated user-manual.xml is identical before and after this patch. Asciidoctor now creates the same chapter-section-subsection structure as AsciiDoc. Changing the book title at the start of the document to similarly use "=" instead of a line of equal signs makes no difference with any of the engines, but let's do that change anyway for consistency. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-28user-manual.txt: add missing section labelLibravatar Martin Ågren1-0/+1
We provide a label for each chapter and section except for the "Pitfalls with submodules" section. Since we're doing it everywhere else, let's do it here, too. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07doc: promote "git restore"Libravatar Nguyễn Thái Ngọc Duy1-7/+5
The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07user-manual.txt: prefer 'merge --abort' over 'reset --hard'Libravatar Nguyễn Thái Ngọc Duy1-1/+1
Since the operation in progress is merge, stick to the 'git merge' variant of aborting. 'git reset --hard' does not really tell you about aborting the merge by just looking, longer to type, and even though I know by heart what --hard do, I still dislike it when I need to consider whether --hard, --mixed or --soft. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02doc: promote "git switch"Libravatar Nguyễn Thái Ngọc Duy1-28/+28
The new command "git switch" is added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguation context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands... The "Checking out files" progress line in unpack-trees.c is also updated to "Updating files" to be neutral to both git-checkout and git-switch. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-12-06checkout: describe_detached_head: remove ellipsis after committishLibravatar Ann T Ropea1-1/+1
We do not want an ellipsis displayed following an (abbreviated) SHA-1 value. The days when this was necessary to indicate the truncation to lower-level Git commands and/or the user are bygone. However, to ease the transition, the ellipsis will still be printed if the user sets the environment variable GIT_PRINT_SHA1_ELLIPSIS to "yes". Correct documentation with respect to what describe_detached_head prints when GIT_PRINT_SHA1_ELLIPSIS is not set as indicated above. Add tests for the old and new behaviour. Signed-off-by: Ann T Ropea <bedhanger@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-12-04Documentation: user-manual: limit usage of ellipsisLibravatar Ann T Ropea1-10/+10
There is no need to use full 40-hex to identify the object names like the examples hint at by omitting the tail part of an object name as if that has to be spelled out but the example omits them only for brevity. Give examples using abbreviated object names without ellipses just like how people do in real life. Signed-off-by: Ann T Ropea <bedhanger@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-10-27stash: replace "git stash save" with "git stash push" in the documentationLibravatar Thomas Gummerer1-1/+1
"git stash push" is the newer interface for creating a stash. While we are still keeping "git stash save" around for the time being, it's better to point new users of "git stash" to the more modern (and more feature rich) interface, instead of teaching them the older version that we might want to phase out in the future. Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-23treewide: correct several "up-to-date" to "up to date"Libravatar Martin Ågren1-1/+1
Follow the Oxford style, which says to use "up-to-date" before the noun, but "up to date" after it. Don't change plumbing (specifically send-pack.c, but transport.c (git push) also has the same string). This was produced by grepping for "up-to-date" and "up to date". It turned out we only had to edit in one direction, removing the hyphens. Fix a typo in Documentation/git-diff-index.txt while we're there. Reported-by: Jeffrey Manian <jeffrey.manian@gmail.com> Reported-by: STEVEN WHITE <stevencharleswhitevoices@gmail.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-23Documentation/user-manual: update outdated example outputLibravatar Martin Ågren1-4/+6
Since commit f7673490 ("more terse push output", 2007-11-05), git push has a completely different output format than the one shown in the user manual for a non-fast-forward push. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-13asciidoctor: fix user-manual to be built by `asciidoctor`Libravatar 마누엘1-0/+8
The `user-manual.txt` is designed as a `book` but the `Makefile` wants to build it as an `article`. This seems to be a problem when building the documentation with `asciidoctor`. Furthermore the parts *Git Glossary* and *Appendix B* had no subsections which is not allowed when building with `asciidoctor`. So lets add a *dummy* section. Signed-off-by: 마누엘 <nalla@hamal.uberspace.de> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-03-03documentation: fix some typosLibravatar Thomas Ackermann1-1/+1
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-20Merge branch 'ss/user-manual'Libravatar Junio C Hamano1-10/+31
Drop a few old "todo" items by deciding that the change one of them suggests is not such a good idea, and doing the change the other one suggested to do. * ss/user-manual: user-manual: add addition gitweb information user-manual: add section documenting shallow clones glossary: define the term shallow clone user-manual: remove temporary branch entry from todo list
2015-12-30user-manual: add addition gitweb informationLibravatar Stephen P. Smith1-4/+11
Rework the section on gitweb to add information about the cgi script and the instaweb command. Signed-off-by: Stephen P. Smith <ischis2@cox.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-12-30user-manual: add section documenting shallow clonesLibravatar Stephen P. Smith1-3/+20
Signed-off-by: Stephen P. Smith <ischis2@cox.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-12-28user-manual: remove temporary branch entry from todo listLibravatar Stephen P. Smith1-3/+0
In the section on "How to check out a different version of a project" the "new" branch is used as a temporary branch. A detached HEAD was not used since it was a new feature introduced just a couple weeks prior. The section could be changed to use and explain a detached HEAD, except that would increase the learning curve early in the manual. Detached HEADs are discussed a couple sections later under "Examining an old version without creating a new branch". Let's declare that it is a bad idea to rewrite the example that uses a temporary branch to do the sightseeing on a detached HEAD. Signed-off-by: Stephen P. Smith <ischis2@cox.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-30Merge branch 'xf/user-manual-ff'Libravatar Junio C Hamano1-5/+5
* xf/user-manual-ff: user-manual: fix the description of fast-forward
2015-10-29Merge branch 'xf/user-manual-markup'Libravatar Junio C Hamano1-1/+1
AsciiDoc markup fixes. * xf/user-manual-markup: Documentation: match undefline with the text in old release notes Documentation: match underline with the text Documentation: fix header markup
2015-10-26user-manual: fix the description of fast-forwardLibravatar Xue Fuqiao1-5/+5
The "Fast-forward merges" section of user-manual.txt incorrectly says if the current branch is a descendant of the other, Git will perform a fast-forward merge, but it should the other way around. Signed-off-by: Xue Fuqiao <xfq.free@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-22Documentation: fix header markupLibravatar Xue Fuqiao1-1/+1
Asciidoctor is stricter than AsciiDoc when deciding if underlining is a section title or the start of preformatted text. Make the length of the underlining match the text to ensure that it renders correctly in all implementations. Signed-off-by: Xue Fuqiao <xfq.free@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-14Merge branch 'jk/asciidoctor-section-heading-markup-fix'Libravatar Junio C Hamano1-1/+1
* jk/asciidoctor-section-heading-markup-fix: Documentation: fix section header mark-up
2015-09-25Documentation: fix section header mark-upLibravatar John Keeping1-1/+1
Asciidoctor is stricter than AsciiDoc when deciding if underlining is a section title or the start of preformatted text. Make the length of the underlining match the text to ensure that it renders correctly in all implementations. Signed-off-by: John Keeping <john@keeping.me.uk> [jc: squashed in git-bisect one noticed by Michael J Gruber] Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-1/+1
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-06-16Merge branch 'jm/doc-wording-tweaks'Libravatar Junio C Hamano1-8/+7
* jm/doc-wording-tweaks: Documentation: wording fixes in the user manual and glossary
2014-05-28Documentation: wording fixes in the user manual and glossaryLibravatar Jeremiah Mahler1-8/+7
Re-word the section on "Updating a repository with git fetch" in the user manual. Various other minor fixes in the manual and glossary. Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-21Documentation: use "command-line" when used as a compound adjective, and fix ↵Libravatar Jason St. John1-2/+2
other minor grammatical issues Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-03-31Documentation: fix misuses of "nor"Libravatar Justin Lebar1-1/+1
Signed-off-by: Justin Lebar <jlebar@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-02-07Merge branch 'ow/manpages-typofix'Libravatar Junio C Hamano1-1/+1
Various typofixes, all looked correct. * ow/manpages-typofix: Documentation: fix typos in man pages
2014-02-05Documentation: fix typos in man pagesLibravatar Øystein Walle1-1/+1
Signed-off-by: Øystein Walle <oystwa@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-01-06user-manual: improve html and pdf formattingLibravatar Thomas Ackermann1-1/+1
Use asciidoc style 'article' instead of 'book' and change asciidoc title level. This removes blank first page and superfluous "Part I" page (there is no "Part II") in pdf output. Also pdf size is decreased by this from 77 to 67 pages. In html output this removes unnecessary sub-tocs and chapter numbering. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-17Merge branch 'ss/doclinks'Libravatar Junio C Hamano1-2/+2
When we converted many documents that were traditionally text-only to be formatted to AsciiDoc, we did not update links that point at them to refer to the formatted HTML files. * ss/doclinks: Documentation: make AsciiDoc links always point to HTML files
2013-09-06Documentation: make AsciiDoc links always point to HTML filesLibravatar Sebastian Schuberth1-2/+2
AsciiDoc's "link" is supposed to create hyperlinks for HTML output, so prefer a "link" to point to an HTML file instead of a text file if an HTML version of the file is being generated. For RelNotes, keep pointing to text files as no equivalent HTML files are generated. If appropriate, also update the link description to not contain the linked file's extension. Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27"git prune" is safeLibravatar Thomas Ackermann1-9/+3
"git prune" is safe in case of concurrent accesses to a repository but using it in such a case is not recommended. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Remove irrelevant reference from "Tying it all together"Libravatar Thomas Ackermann1-2/+1
Sorry Jon, but this might not be of any help to new Git users ;) Acked-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Remove unnecessary historical note from "Object storage format"Libravatar Thomas Ackermann1-2/+0
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Improve section "Merging multiple trees"Libravatar Thomas Ackermann1-14/+13
Remove unnecessary quoting. Simplify description of three-way merge. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Improve section "Manipulating branches"Libravatar Thomas Ackermann1-12/+8
Add some missing punctuation. Simplify description of "git branch -d/-D". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Simplify "How to make a commit"Libravatar Thomas Ackermann1-8/+2
Combine the two cases for "git add" into one. Add verb "use" to "git rm" case. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Fix some typos and improve wordingLibravatar Thomas Ackermann1-10/+10
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Use "git merge" instead of "git pull ."Libravatar Thomas Ackermann1-4/+4
"git pull ." works, but "git merge" is the recommended way for new users to do things. (The old description also should have read "The former is actually *not* very commonly used".) Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Use current output for "git repack"Libravatar Thomas Ackermann1-9/+7
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Use current "detached HEAD" messageLibravatar Thomas Ackermann1-6/+13
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-27Call it "Git User Manual" and remove reference to very old Git versionLibravatar Thomas Ackermann1-3/+2
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-22Sync with Git 1.8.3.4Libravatar Junio C Hamano1-2/+2
2013-07-22update URL to the marc.info mail archiveLibravatar Ondřej Bílka1-2/+2
The name marc.theaimsgroup.com is no longer active, and has migrated to marc.info. Signed-off-by: Ondřej Bílka <neleai@seznam.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-21Merge branch 'ph/builtin-srcs-are-in-subdir-these-days' into maintLibravatar Junio C Hamano1-6/+7
* ph/builtin-srcs-are-in-subdir-these-days: fix "builtin-*" references to be "builtin/*"
2013-07-01Merge branch 'kb/am-deprecate-resolved'Libravatar Junio C Hamano1-1/+1
Promote "git am --continue" over "git am --resolved" for UI consistency. * kb/am-deprecate-resolved: am: replace uses of --resolved with --continue
2013-07-01Merge branch 'wk/doc-in-linux-3.x-era'Libravatar Junio C Hamano1-14/+20
Update documentation to match more recent realities. * wk/doc-in-linux-3.x-era: Documentation: Update 'linux-2.6.git' -> 'linux.git' Documentation: Update the NFS remote examples to use the staging repo doc/clone: Pick more compelling paths for the --reference example doc/clone: Remove the '--bare -l -s' example
2013-06-27am: replace uses of --resolved with --continueLibravatar Kevin Bracey1-1/+1
git am was previously modified to provide --continue for consistency with rebase, merge etc, and the documentation changed to showing --continue as the primary form. Complete the work by replacing remaining uses of --resolved by --continue, most notably in suggested command reminders. Signed-off-by: Kevin Bracey <kevin@bracey.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>