From 1f010d6bdf756129db13d1367c888aa4153f6d87 Mon Sep 17 00:00:00 2001
From: "brian m. carlson" <sandals@crustytoothpaste.net>
Date: Mon, 20 Jan 2025 01:56:02 +0000
Subject: doc: use .adoc extension for AsciiDoc files

We presently use the ".txt" extension for our AsciiDoc files.  While not
wrong, most editors do not associate this extension with AsciiDoc,
meaning that contributors don't get automatic editor functionality that
could be useful, such as syntax highlighting and prose linting.

It is much more common to use the ".adoc" extension for AsciiDoc files,
since this helps editors automatically detect files and also allows
various forges to provide rich (HTML-like) rendering.  Let's do that
here, renaming all of the files and updating the includes where
relevant.  Adjust the various build scripts and makefiles to use the new
extension as well.

Note that this should not result in any user-visible changes to the
documentation.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-replace.adoc | 161 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 Documentation/git-replace.adoc

(limited to 'Documentation/git-replace.adoc')

diff --git a/Documentation/git-replace.adoc b/Documentation/git-replace.adoc
new file mode 100644
index 0000000000..0a65460adb
--- /dev/null
+++ b/Documentation/git-replace.adoc
@@ -0,0 +1,161 @@
+git-replace(1)
+==============
+
+NAME
+----
+git-replace - Create, list, delete refs to replace objects
+
+SYNOPSIS
+--------
+[verse]
+'git replace' [-f] <object> <replacement>
+'git replace' [-f] --edit <object>
+'git replace' [-f] --graft <commit> [<parent>...]
+'git replace' [-f] --convert-graft-file
+'git replace' -d <object>...
+'git replace' [--format=<format>] [-l [<pattern>]]
+
+DESCRIPTION
+-----------
+Adds a 'replace' reference in `refs/replace/` namespace.
+
+The name of the 'replace' reference is the SHA-1 of the object that is
+replaced. The content of the 'replace' reference is the SHA-1 of the
+replacement object.
+
+The replaced object and the replacement object must be of the same type.
+This restriction can be bypassed using `-f`.
+
+Unless `-f` is given, the 'replace' reference must not yet exist.
+
+There is no other restriction on the replaced and replacement objects.
+Merge commits can be replaced by non-merge commits and vice versa.
+
+Replacement references will be used by default by all Git commands
+except those doing reachability traversal (prune, pack transfer and
+fsck).
+
+It is possible to disable the use of replacement references for any
+command using the `--no-replace-objects` option just after 'git'.
+
+For example if commit 'foo' has been replaced by commit 'bar':
+
+------------------------------------------------
+$ git --no-replace-objects cat-file commit foo
+------------------------------------------------
+
+shows information about commit 'foo', while:
+
+------------------------------------------------
+$ git cat-file commit foo
+------------------------------------------------
+
+shows information about commit 'bar'.
+
+The `GIT_NO_REPLACE_OBJECTS` environment variable can be set to
+achieve the same effect as the `--no-replace-objects` option.
+
+OPTIONS
+-------
+-f::
+--force::
+	If an existing replace ref for the same object exists, it will
+	be overwritten (instead of failing).
+
+-d::
+--delete::
+	Delete existing replace refs for the given objects.
+
+--edit <object>::
+	Edit an object's content interactively. The existing content
+	for <object> is pretty-printed into a temporary file, an
+	editor is launched on the file, and the result is parsed to
+	create a new object of the same type as <object>. A
+	replacement ref is then created to replace <object> with the
+	newly created object. See linkgit:git-var[1] for details about
+	how the editor will be chosen.
+
+--raw::
+	When editing, provide the raw object contents rather than
+	pretty-printed ones. Currently this only affects trees, which
+	will be shown in their binary form. This is harder to work with,
+	but can help when repairing a tree that is so corrupted it
+	cannot be pretty-printed. Note that you may need to configure
+	your editor to cleanly read and write binary data.
+
+--graft <commit> [<parent>...]::
+	Create a graft commit. A new commit is created with the same
+	content as <commit> except that its parents will be
+	[<parent>...] instead of <commit>'s parents. A replacement ref
+	is then created to replace <commit> with the newly created
+	commit. Use `--convert-graft-file` to convert a
+	`$GIT_DIR/info/grafts` file and use replace refs instead.
+
+--convert-graft-file::
+	Creates graft commits for all entries in `$GIT_DIR/info/grafts`
+	and deletes that file upon success. The purpose is to help users
+	with transitioning off of the now-deprecated graft file.
+
+-l <pattern>::
+--list <pattern>::
+	List replace refs for objects that match the given pattern (or
+	all if no pattern is given).
+	Typing "git replace" without arguments, also lists all replace
+	refs.
+
+--format=<format>::
+	When listing, use the specified <format>, which can be one of
+	'short', 'medium' and 'long'. When omitted, the format
+	defaults to 'short'.
+
+FORMATS
+-------
+
+The following formats are available:
+
+* 'short':
+	<replaced-sha1>
+* 'medium':
+	<replaced-sha1> -> <replacement-sha1>
+* 'long':
+	<replaced-sha1> (<replaced-type>) -> <replacement-sha1> (<replacement-type>)
+
+CREATING REPLACEMENT OBJECTS
+----------------------------
+
+linkgit:git-hash-object[1], linkgit:git-rebase[1], and
+https://github.com/newren/git-filter-repo[git-filter-repo], among other git commands, can be used to
+create replacement objects from existing objects. The `--edit` option
+can also be used with 'git replace' to create a replacement object by
+editing an existing object.
+
+If you want to replace many blobs, trees or commits that are part of a
+string of commits, you may just want to create a replacement string of
+commits and then only replace the commit at the tip of the target
+string of commits with the commit at the tip of the replacement string
+of commits.
+
+BUGS
+----
+Comparing blobs or trees that have been replaced with those that
+replace them will not work properly. And using `git reset --hard` to
+go back to a replaced commit will move the branch to the replacement
+commit instead of the replaced commit.
+
+There may be other problems when using 'git rev-list' related to
+pending objects.
+
+SEE ALSO
+--------
+linkgit:git-hash-object[1]
+linkgit:git-rebase[1]
+linkgit:git-tag[1]
+linkgit:git-branch[1]
+linkgit:git-commit[1]
+linkgit:git-var[1]
+linkgit:git[1]
+https://github.com/newren/git-filter-repo[git-filter-repo]
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
cgit v1.3

