The standard for command documentation synopses appears to be:
[...] means optional
<...> means replaceable
[<...>] means both optional and replaceable
So fix a number of doc pages that use incorrect variations of the
above.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When formatted as a man page, 1st section header is always in upper
case even if we write it otherwise. Make all 1st section headers
uppercase to keep it close to the final output.
This does affect html since case is kept there, but I still think it's
a good idea to maintain a consistent style for 1st section headers.
Some sections perhaps should become second sections instead, where
case is kept, and for better organization. I will update if anyone has
suggestions about this.
While at there I also make some header more consistent (e.g. examples
vs example) and fix a couple minor things here and there.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
This is an application of the newly added CodingGuidelines to HEAD and
variants like FETCH_HEAD. It was obtained with:
perl -pi -e "s/'([A-Z_]*HEAD)'/\`\$1\`/g" *.txt
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Similarly to the previous commit, use backquotes instead of
forward-quotes, for long options.
This was obtained with:
perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt
and manual tweak to remove false positive in ascii-art (o'--o'--o' to
describe rewritten history).
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It was common in our documentation to surround short option names with
forward quotes, which renders as italic in HTML. Instead, use backquotes
which renders as monospace. This is one more step toward conformance to
Documentation/CodingGuidelines.
This was obtained with:
perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
In addition to fixing trivial and obvious typos, be careful about
the following points:
- Spell ASCII, URL and CRC in ALL CAPS;
- Spell Linux as Capitalized;
- Do not omit periods in "i.e." and "e.g.".
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Update documentation to change "GIT" which was a poor-man's small
caps to "Git". The latter was the intended spelling.
Also change "git" spelled in all-lowercase to "Git" when it refers
to the system as the whole or the concept it embodies, as opposed to
the command the end users would type.
* ta/doc-no-small-caps:
Documentation: StGit is the right spelling, not StGIT
Documentation: describe the "repository" in repository-layout
Documentation: add a description for 'gitfile' to glossary
Documentation: do not use undefined terms git-dir and git-file
Documentation: the name of the system is 'Git', not 'git'
Documentation: avoid poor-man's small caps GIT
In the earlier days, we used to spell the name of the system as GIT,
to simulate as if it were typeset with capital G and IT in small
caps. Later we stopped doing so at around 1.6.5 days.
Let's stop doing so throughout the documentation. The name to refer
to the whole system (and the concept it embodies) is "Git"; the
command end-users type is "git". And document this in the coding
guideline.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Recent versions of asciidoc will treat "->" as a
single-glyph arrow symbol, unless it is inside a literal
code block. This is a problem if we are discussing literal
output and want to show the ASCII characters.
Our usage falls into three categories:
1. Inside a code block. These can be left as-is.
2. Discussing literal output or code, but inside a
paragraph. This patch escapes these as "\->".
3. Using the arrow as a symbolic element, such as "use the
Edit->Account Settings menu". In this case, the
arrow symbol is preferable, so we leave it as-is.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The point of these sections is generally to:
1. Give credit where it is due.
2. Give the reader an idea of where to ask questions or
file bug reports.
But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame. For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.
So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.
Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.
This perl snippet is useful for quickly making a password without
htpasswd(1).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If a git repository is shared via HTTP, the config file is typically
visible. Use an external file instead.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Allow git-cvsserver to use authentication over pserver mode. The
pserver user/password database is stored in the config file for each
repository.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Worriedly-Acked-by: Martin Langhoff <martin.langhoff@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As discussed on the list, "crlf" is not an optimal name. Linus
suggested "text", which is much better.
Signed-off-by: Eyvind Bernhardsen <eyvind.bernhardsen@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* remotes/trast-doc/for-next:
Documentation: spell 'git cmd' without dash throughout
Documentation: format full commands in typewriter font
Documentation: warn prominently against merging with dirty trees
Documentation/git-merge: reword references to "remote" and "pull"
Conflicts:
Documentation/config.txt
Documentation/git-config.txt
Documentation/git-merge.txt
The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.
The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.
Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.
Use `code snippet` style instead of 'emphasis' for `git cmd ...`
according to the following rules:
* The SYNOPSIS sections are left untouched.
* If the intent is that the user type the command exactly as given, it
is `code`.
If the user is only loosely referred to a command and/or option, it
remains 'emphasised'.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
The Gitosis single-account Git/ssh hosting system runs git commands
through git-shell after confirming that the connecting user is
authorized to access the requested repository. This works well for
upload-pack and receive-pack, which take a repository argument through
git-shell. This doesn't work so well for `cvs server', which is passed
through literally, with no arguments. Allowing arguments risks
sneaking in `--export-all', so that restriction should be maintained.
Despite that, passing a repository root is necessary for per-user
access control by the hosting software, and passing a base path
improves usability without weakening security. Thus, git-cvsserver
needs to come up with these values at runtime by some other
means. Since git-shell preserves the environment for other purposes,
the environment can carry these arguments as well.
Thus, modify git-cvsserver to read $GIT_CVSSERVER_{BASE_PATH,ROOT} in
the absence of equivalent command line arguments.
Signed-off-by: Phil Miller <mille121@illinois.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A regenerated git-cvsserver database is at risk of having different
CVS revision numbers from an incrementally updated database. Mention
this in the the documentation, and remove an erroneous statement
to the contrary.
Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* qq/maint:
clone -q: honor "quiet" option over native transports.
attribute documentation: keep EXAMPLE at end
builtin-commit.c: Use 'git_config_string' to get 'commit.template'
http.c: Use 'git_config_string' to clean up SSL config.
diff.c: Use 'git_config_string' to get 'diff.external'
convert.c: Use 'git_config_string' to get 'smudge' and 'clean'
builtin-log.c: Use 'git_config_string' to get 'format.subjectprefix' and 'format.suffix'
Documentation cvs: Clarify when a bare repository is needed
Documentation: be precise about which date --pretty uses
Conflicts:
Documentation/gitattributes.txt
New users sometimes import a project and then immediately
try to use the imported repository as a central shared repository.
This provides pointers about setting up a bare repository for that
in the parts of the documentation dealing with CVS migration.
Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Some manual pages use teletype font to set command names. We
change them to use italics, instead. This creates a visual
distinction between names of commands and command lines that
can be typed at the command line. It is also more consistent
with other man pages outside Git.
In this patch, the commands named are non-git commands like bash.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The names of git commands are not meant to be entered at the
commandline; they are just names. So we render them in italics,
as is usual for command names in manpages.
Using
doit () {
perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }'
}
for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \
merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt
do
doit <"$i" >"$i+" && mv "$i+" "$i"
done
git diff
.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.
While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since the git-* commands are not installed in $(bindir), using
"git-command <parameters>" in examples in the documentation is
not a good idea. On the other hand, it is nice to be able to
refer to each command using one hyphenated word. (There is no
escaping it, anyway: man page names cannot have spaces in them.)
This patch retains the dash in naming an operation, command,
program, process, or action. Complete command lines that can
be entered at a shell (i.e., without options omitted) are
made to use the dashless form.
The changes consist only of replacing some spaces with hyphens
and vice versa. After a "s/ /-/g", the unpatched and patched
versions are identical.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The OPTIONS section of a documentation file contains a list
of the options a git command accepts.
Currently there are several variants to describe the case that
different options (almost) do the same in the OPTIONS section.
Some are:
-f, --foo::
-f|--foo::
-f | --foo::
But AsciiDoc has the special form:
-f::
--foo::
This patch applies this form to the documentation of the whole git suite,
and removes useless em-dash prevention, so \--foo becomes --foo.
Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As the "git" man page describes the "git" command at the end-user
level, it seems better to move it to man section 1.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With xmlto 0.0.18 it seems to demand that no section levels are
skipped. The commit 'implement gitcvs.usecrlfattr' (8a06a63297)
one such skip, which here is removed by increasing the level of the
offender.
Signed-off-by: Gustaf Hendeby <hendeby@isy.liu.se>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If "gitcvs.allbinary" is set to "guess", then any file that has
not been explicitly marked as binary or text using the "crlf" attribute
and the "gitcvs.usecrlfattr" config will guess binary based on the contents
of the file.
Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If gitcvs.usecrlfattr is set to true, git-cvsserver will consult
the "crlf" for each file to determine if it should mark the file
as binary (-kb).
Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint-1.5.4:
git-bisect: make "start", "good" and "skip" succeed or fail atomically
git-am: cope better with an empty Subject: line
Ignore leading empty lines while summarizing merges
bisect: squelch "fatal: ref HEAD not a symref" misleading message
builtin-apply: Show a more descriptive error on failure when opening a patch
Clarify documentation of git-cvsserver, particularly in relation to git-shell
For SSH clients restricted to git-shell, CVS_SERVER does not have to be
specified, because git-shell understands the default value of 'cvs' to
mean git-cvsserver'. This makes it totally transparent to CVS users, but
the instruction to set up CVS access for people with real shell access
does not apply.
Previous wording mentioning GIT_AUTHOR, GIT_COMMITTER variables was
unclear that we really meant GIT_AUTHOR_(NAME|EMAIL), etc.
Note that the .ssh/environment file is a good place to set these, and that
the .bashrc is shell-specific. Add a bit of text to differentiate cvs -d
(setting CVSROOT) from cvs co -d (setting the name of the newly checked
out directory). Removed an extra 'Example:' string.
Signed-off-by: Scott Collins <scc@ScottCollins.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adds a gitcvs.dbtablenameprefix config variable, the contents of which
are prepended to any database tables names used by git-cvsserver. The
same substutions as gitcvs.dbname and gitcvs.dbuser are supported, and
any non-alphabetic characters are replaced with underscores.
A typo found in contrib/completion/git-completion.bash is also fixed.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock
Asciidoc configuration:
@@ -149,7 +153,10 @@
# Inline macros.
# Backslash prefix required for escape processing.
# (?s) re flag for line spanning.
-(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
+# Explicit so they can be nested.
+(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
# Anchor: [[[id]]]. Bibliographic anchor.
(?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3
# Anchor: [[id,xreflabel]]
This default regex now matches explicit values, and unfortunately in this
case gitlink was being matched by just 'link', causing the wrong inline
macro template to be applied. By renaming the macro, we can avoid being
matched by the wrong regex.
Signed-off-by: Dan McGee <dpmcgee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When not referring to the cvs command, CVS makes more sense.
Signed-off-by: Brian Hetro <whee@smaertness.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Embarrassing bug number two in my options patch.
Also enforce that --export-all is only ever used together with an
explicit whitelist. Otherwise people might export every git repository
on the whole system without realising.
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make git-cvsserver understand some options inspired by
git-daemon, namely --base-path, --export-all, --strict-paths.
Also allow the caller to specify a whitelist of allowed
directories, again similar to git-daemon.
While already adding option parsing also support the common
--help and --version options.
Rationale:
While the gitcvs.enabled configuration option already
offers means to limit git-cvsserver access to a repository,
there are some use cases where other methods of access
control prove to be more useful.
E.g. if setting up a pserver for a collection of public
repositories one might want limit the exported repositories
to exactly the directory this collection is located whithout
having to worry about other repositories that might lie around
with the configuration variable set (never trust your users ;)
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Reasonably new versions of the cvs CLI client allow one to
specifiy CVS_SERVER as a method variable directly in
CVSROOT. This is way more convinient than using an
environment variable since it gets saved in CVS/Root.
Since I only discovered this by accident I guess there
might be others out there that learnt CVS on the 1.11
series (or even earlier) and profit from such a note
about cvs improvements in the last couple years.
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Robert P. J. Day
Nguyễn Thái Ngọc Duy
Martin Ågren
Matthieu Moy
Thomas Ackermann
Junio C Hamano
Matthew Ogilvie
Jeff King
Ville Skyttä
Ævar Arnfjörð Bjarmason
Sam Vilain
Eyvind Bernhardsen
Thomas Rast
Phil Miller
Robert Schiele
Jonathan Nieder
Stephan Beyer
Christian Couder
Gustaf Hendeby
Scott Collins
Josh Elsasser
Jean-Luc Herren
Jim Meyering
Dan McGee
Brian Hetro
Frank Lichtenheld