Commit graph

22 commits

Author SHA1 Message Date
Nguyễn Thái Ngọc Duy 76a8788c14 doc: keep first level section header in upper case
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>
2018-05-02 17:03:33 +09:00
David Turner 144c76fa39 update-ref and tag: add --create-reflog arg
Allow the creation of a ref (e.g. stash) with a reflog already in
place. For most refs (e.g. those under refs/heads), this happens
automatically, but for others, we need this option.

Currently, git does this by pre-creating the reflog, but alternate ref
backends might store reflogs somewhere other than .git/logs.  Code
that now directly manipulates .git/logs should instead use git
plumbing commands.

I also added --create-reflog to git tag, just for completeness.

In a moment, we will use this argument to make git stash work with
alternate ref backends.

Signed-off-by: David Turner <dturner@twopensource.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-07-21 14:08:35 -07:00
Michael Haggerty 1fbd504942 update-ref --stdin -z: deprecate interpreting the empty string as zeros
In the original version of this command, for the single case of the
"update" command's <newvalue>, the empty string was interpreted as
being equivalent to 40 "0"s.  This shorthand is unnecessary (binary
input will usually be generated programmatically anyway), and it
complicates the parser and the documentation.

So gently deprecate this usage: remove its description from the
documentation and emit a warning if it is found.  But for reasons of
backwards compatibility, continue to accept it.

Helped-by: Brad King <brad.king@kitware.com>
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-07 12:09:13 -07:00
Brad King c750ba9519 update-ref: support multiple simultaneous updates
Add a --stdin signature to read update instructions from standard input
and apply multiple ref updates together.  Use an input format that
supports any update that could be specified via the command-line,
including object names like "branch:path with space".

Signed-off-by: Brad King <brad.king@kitware.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-09 09:54:37 -07:00
Thomas Ackermann 48a8c26c62 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>
2013-02-01 13:53:25 -08:00
Junio C Hamano ef6663b3db Merge branch 'bw/log-all-ref-updates-doc'
* bw/log-all-ref-updates-doc:
  Documentation: clearly specify what refs are honored by core.logAllRefUpdates
2011-07-22 14:43:51 -07:00
Bert Wesarg cd8e3711bf Documentation: clearly specify what refs are honored by core.logAllRefUpdates
The documentation for logging updates in git-update-ref, doesn't make it
clear that only a specific subset of refs are honored by this variable.

Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-12 09:11:14 -07:00
Martin von Zweigbergk 7791a1d9b9 Documentation: use [verse] for SYNOPSIS sections
The SYNOPSIS sections of most commands that span several lines already
use [verse] to retain line breaks. Most commands that don't span
several lines seem not to use [verse]. In the HTML output, [verse]
does not only preserve line breaks, but also makes the section
indented, which causes a slight inconsistency between commands that
use [verse] and those that don't. Use [verse] in all SYNOPSIS sections
for consistency.

Also remove the blank lines from git-fetch.txt and git-rebase.txt to
align with the other man pages. In the case of git-rebase.txt, which
already uses [verse], the blank line makes the [verse] not apply to
the last line, so removing the blank line also makes the formatting
within the document more consistent.

While at it, add single quotes to 'git cvsimport' for consistency with
other commands.

Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-06 14:26:26 -07:00
Jeff King 48bb914ed6 doc: drop author/documentation sections from most pages
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.
2011-03-11 10:59:16 -05:00
Jonathan Nieder b1889c36d8 Documentation: be consistent about "git-" versus "git "
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>
2008-07-01 17:20:15 -07:00
Junio C Hamano 66915b5d7c Merge branch 'kh/update-ref'
* kh/update-ref:
  Make old sha1 optional with git update-ref -d
  Clean up builtin-update-ref's option parsing
2008-06-22 14:31:57 -07:00
Christian Couder 9e1f0a85c6 documentation: move git(7) to git(1)
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>
2008-06-06 11:18:28 -07:00
Karl Hasselström 3fe8dce6fc Make old sha1 optional with git update-ref -d
Giving the old sha1 is already optional when changing a ref, and it's
quite handy when running update-ref manually. So make it optional for
deleting a ref too.

Signed-off-by: Karl Hasselström <kha@treskal.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-02 22:52:39 -07:00
Dan McGee 5162e69732 Documentation: rename gitlink macro to linkgit
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>
2008-01-06 18:41:44 -08:00
Sven Verdoolaege 68db31cc28 git-update-ref: add --no-deref option for overwriting/detaching ref
git-checkout is also adapted to make use of this new option
instead of the handcrafted command sequence.

Signed-off-by: Sven Verdoolaege <skimo@kotnet.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-05-10 15:24:44 -07:00
Junio C Hamano c3f0baacad Documentation: sync git.txt command list and manual page title
Also reorders a handful entries to make each list sorted
alphabetically.

Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-18 15:53:37 -08:00
Junio C Hamano ac5409e420 update-ref: -d flag and ref creation safety.
This adds -d flag to update-ref to allow safe deletion of ref.
Before deleting it, the command checks if the given <oldvalue>
still matches the value the caller thought the ref contained.

Similarly, it also accepts 0{40} or an empty string as <oldvalue>
to allow safe creation of a new ref.

Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-09-27 02:01:42 -07:00
Shawn Pearce 7792cc2fa1 Change order of -m option to update-ref.
The actual position doesn't matter but most people prefer to see
options appear before the arguments.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-19 15:03:10 -07:00
Shawn Pearce 6de08ae688 Log ref updates to logs/refs/<ref>
If config parameter core.logAllRefUpdates is true or the log
file already exists then append a line to ".git/logs/refs/<ref>"
whenever git-update-ref <ref> is executed.  Each log line contains
the following information:

  oldsha1 <SP> newsha1 <SP> committer <LF>

where committer is the current user, date, time and timezone in
the standard GIT ident format.  If the caller is unable to append
to the log file then git-update-ref will fail without updating <ref>.

An optional message may be included in the log line with the -m flag.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-17 17:36:36 -07:00
Shawn Pearce 5b16b09021 Convert update-ref to use ref_lock API.
This conversion also adds the '-m' switch to update-ref allowing
the caller to record why the ref is changing.  At present this is
merely copied down into the ref_lock API.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-17 17:36:36 -07:00
Dmitry V. Levin bd494fc76b git/Documentation: fix SYNOPSIS style bugs
This trivial patch fixes SYNOPSIS style bugs.

Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-03-05 17:02:02 -08:00
Junio C Hamano 129056370a Add missing documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-10-04 17:04:03 -07:00