Merge branch 'main' into cobra-update

CONTRIBUTING.md

@@ -152,9 +152,10 @@ $ script/cibuild     # runs everything, with verbose debug output
 
 ## Updating 3rd party packages
 
-1. Update `go.mod`.
-1. Run `make vendor` to update the code in the `vendor` directory.
-1. Commit the change.  Git LFS vendors the full source code in the repository.
+1. Update `go.mod` and `go.sum`. You can ensure the latter is up-to-date by
+   using Go tools instead of manually editing `go.mod` (e.g., `go get
+   gopath@version`) or by running `go mod tidy` or `make go.sum`.
+1. Commit the change.
 1. Submit a pull request.
 
 ## Releasing

Makefile

@@ -232,7 +232,7 @@ mangen : commands/mancontent_gen.go
 # commands/mancontent_gen.go is generated by running 'go generate' on package
 # 'commands' of Git LFS. It depends upon the contents of the 'docs' directory
 # and converts those manpages into code.
-commands/mancontent_gen.go : $(wildcard docs/man/*.ronn)
+commands/mancontent_gen.go : $(wildcard docs/man/*.adoc)
 	GOOS= GOARCH= $(GO) generate github.com/git-lfs/git-lfs/v3/commands
 
 # trgen is a shorthand for ensuring that tr/tr_gen.go is kept up-to-date with

docs/man/git-lfs-faq.adoc

@@ -6,6 +6,10 @@ git-lfs-faq - FAQ for Git LFS
 
 == ENTRIES
 
+[[cat-file-size]]
+=== File Size
+
+[[faq-track-by-size]]
 Does Git LFS provide a way to track files by size?::
   No, it doesn't.  Unfortunately, Git itself doesn't specify a way to make
   `.gitattributes` patterns apply to files of a certain size and we rely on
@@ -19,6 +23,7 @@ to track them manually.
 +
 For these reasons, we recommend using patterns rather than `--above`.
 
+[[faq-4gb-windows]]
 Why doesn't Git LFS handle files larger than 4 GiB on Windows?::
   Git LFS itself handles these files just fine.  However, Git LFS is usually
   invoked by Git, and until Git 2.34, Git itself on Windows didn't handle files
@@ -29,6 +34,10 @@ On older versions, set `GIT_LFS_SKIP_SMUDGE` to `1` and run `git lfs pull`
 to pull down the LFS files.  This bypasses Git's smudging functionality
 and therefore avoids its limitations.
 
+[[cat-working-tree-contents]]
+=== Working Tree Contents
+
+[[faq-only-pointer-files]]
 Why do I end up with small text files in my working tree instead of my files?::
   Git LFS stores small text files called pointer files in the repository instead
   of your large files, which it stores elsewhere.  These pointer files usually
@@ -41,6 +50,7 @@ you've explicitly chosen to skip that behaviour by using the `--skip-smudge`
 option of `git lfs install`, then you may need to use `git lfs pull` to replace
 the pointer files in your working tree with large files.
 
+[[faq-working-tree-modified]]
 Why do I end up with some of my working tree files constantly showing as modified?::
   This can happen if someone made a commit to a file that's tracked by Git LFS
   but didn't have Git LFS properly set up on their system.  The objects that
@@ -72,6 +82,10 @@ command `git lfs fsck --pointers BASE..HEAD` (with suitable values of `BASE` and
 `HEAD`) may be used in your CI system to verify that nobody is introducing such
 problems.
 
+[[cat-tracking-and-migration]]
+=== Tracking and Migration
+
+[[faq-track-existing-files]]
 How do I track files that are already in a repository?::
   If you want to track files that already exist in a repository, you need to do
   two things.  First, you need to use `git lfs track` (or a manual modification
@@ -84,36 +98,7 @@ modified, as outlined in the FAQ entry above.  Note also that this doesn't
 change large files in your history.  To do that, use `git lfs migrate import
 --everything` instead, as specified in one of the entries below.
 
-How do I enable git diff to work on LFS files?::
-  You can run `git config diff.lfs.textconv cat`, which will produce normal
-  diffs if your files are text files.
-
-How do I enable git diff to work on LFS files based on extension or path?::
-  If the above solution is too broad, each entry in the `.gitattributes` file
-  can be customized by creating a custom global converter:
-+
-[source,shell-session]
-----
-$ git config --global diff.lfstext.textconv cat
-----
-+
-Any given `.gitattributes` entry for large text files can be customized to use
-  this global text converter (e.g., patch files), whereas binary formats can
-  continue to use the conventional lfs diff tool, like so:
-+
-[source,shell-session]
-----
-$ cat .gitattributes
-....
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.patch filter=lfs diff=lfstext merge=lfs -text
-....
-----
-+
-Be advised that all developers sharing this repo with such a modified
-`.gitattributes` file must have similarly configured the `lfstext` text
-converter, whether globally or on a per repository basis.
-
+[[faq-export-to-git]]
 How do I convert from using Git LFS to a plain Git repository?::
   If you'd like to stop using Git LFS and switch back to storing your large
   files in the plain Git format, you can do so with `git lfs migrate export
@@ -123,6 +108,7 @@ How do I convert from using Git LFS to a plain Git repository?::
 This also rewrites history, so the Git object IDs of many, if not all, of your
 objects will change.
 
+[[faq-github-large-files]]
 I'm using Git LFS, but I still see GitHub's large file error.  How do I fix this?::
   GitHub rejects large files anywhere in the history of your repository, not
   just in the latest commit.  If you're still seeing this message, then you have
@@ -137,23 +123,10 @@ patterns are possible: run `git help gitattributes` for more information on
 valid patterns.  Note that if you're specifying directories, using slashes is
 mandatory: backslashes are not allowed as path separators.
 
-I'm using Jenkins and `git lfs install` fails due to an invalid hook path.  What do I do?::
-  Recent versions of Jenkins have set `core.hooksPath` to various values,
-  notably `NUL:` on Windows, with the goal of disabling hooks.  This is not a
-  valid path on Windows, nor a valid value for this configuration option, so
-  when `git lfs install` runs and Git LFS attempts to install hooks, the
-  operation fails.
-+
-The easiest way to solve this problem is by using the `--skip-repo` option to
-`git lfs install`, which skips the installation of the hooks.  Despite the name,
-it can be successfully combined with `--local` if you need that option.
-+
-Note that this prevents things like `git push` from pushing LFS objects and
-locked files from being read only, since those are implemented by hooks.  If you
-need that functionality, you should review the Jenkins documentation about how
-to properly configure the environment in such a situation so that hooks can be
-used.
+[[cat-configuration]]
+=== Configuration
 
+[[faq-proxy]]
 Can I use a proxy with Git LFS?::
   Yes, Git LFS supports proxies using the same mechanisms that Git supports,
   namely the `http_proxy` environment variable and the configuration of
@@ -175,6 +148,80 @@ developers don't recommend any sort of proxy, including any sort of antivirus,
 firewall, or monitoring software, which performs TLS interception because these
 are known to cause breakage and in general have been shown to worsen security.
 
+[[faq-tls-ca]]
+Can I use a custom set of SSL/TLS certificate authorities with Git LFS?::
+  Yes, Git LFS supports configuring trusted certificate authorities and client
+  certificates for HTTPS, using the same configuration as for Git.
++
+To configure a set of trusted certificate authorities, you can use
+`http.sslCAPath` to specify a directory of files, each one containing a PKCS#1
+certificate of a trusted certificate authority.  If you'd prefer to use a single
+file with all trusted certificates, you can use `http.sslCAInfo` to refer to a
+single file containing PKCS#1 certificates, one following the other.
++
+For example, on Debian, to set this option to provide the default behavior, you
+could run `git config http.sslCAPath /etc/ssl/certs`.  Note that it's also
+possible to set these configuration options on a per-URL basis, like so: `git
+config http.https://example.com/.sslCAPath /etc/ssl/certs`.
++
+Note that PKCS#12 files are a Git for Windows extension to Git and are not
+supported by Git LFS.  Additionally, take into account the information about
+TLS-intercepting proxies above if this configuration is because of a
+TLS-intercepting proxy.
+
+[[faq-tls-client-config]]
+Can I use an SSL/TLS client certificate with Git LFS?::
+  Yes, Git LFS supports configuring client certificates and keys using the same
+  configuration as for Git.
++
+To configure a client certificate, use the `http.sslCert` configuration option
+pointing to a file containing a PKCS#1 certificate.  To configure the
+corresponding key, use `http.sslKey` with a file containing a PEM-encoded key.
+If it is encrypted, you will be prompted using the credential helper for the
+passphrase.
++
+Usually you will want to specify these values on a per-URL basis, such as the
+following: `git config http.https://example.com/.sslKey
+/home/user/.certs/mine.key`.
++
+Note that PKCS#8 and PKCS#12 files are not supported by Git LFS.
+
+[[cat-git-features]]
+=== Working with Git Features
+
+[[faq-git-diff-on-lfs]]
+How do I enable git diff to work on LFS files?::
+  You can run `git config diff.lfs.textconv cat`, which will produce normal
+  diffs if your files are text files.
+
+[[faq-git-diff-on-lfs-by-path]]
+How do I enable git diff to work on LFS files based on extension or path?::
+  If the above solution is too broad, each entry in the `.gitattributes` file
+  can be customized by creating a custom global converter:
++
+[source,shell-session]
+----
+$ git config --global diff.lfstext.textconv cat
+----
++
+Any given `.gitattributes` entry for large text files can be customized to use
+  this global text converter (e.g., patch files), whereas binary formats can
+  continue to use the conventional lfs diff tool, like so:
++
+[source,shell-session]
+----
+$ cat .gitattributes
+....
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.patch filter=lfs diff=lfstext merge=lfs -text
+....
+----
++
+Be advised that all developers sharing this repo with such a modified
+`.gitattributes` file must have similarly configured the `lfstext` text
+converter, whether globally or on a per repository basis.
+
+[[faq-archive-subdirectory]]
 Why are LFS files not included when I archive a subdirectory?::
   When you run `git archive` with only a subdirectory, such as `git archive
   HEAD:src`, Git resolves the revision (in this case, `HEAD:src`) to a tree, and
@@ -210,6 +257,27 @@ bsdtar -s "!^\./!$ARCHIVE_PREFIX!" --format=pax -czf archive.tar.gz -C "$temp/$A
 rm -fr "$temp"
 ----
 
+[[cat-non-git-tools]]
+=== Working with Non-Git Tools
+
+[[faq-jenkins-hooks]]
+I'm using Jenkins and `git lfs install` fails due to an invalid hook path.  What do I do?::
+  Recent versions of Jenkins have set `core.hooksPath` to various values,
+  notably `NUL:` on Windows, with the goal of disabling hooks.  This is not a
+  valid path on Windows, nor a valid value for this configuration option, so
+  when `git lfs install` runs and Git LFS attempts to install hooks, the
+  operation fails.
++
+The easiest way to solve this problem is by using the `--skip-repo` option to
+`git lfs install`, which skips the installation of the hooks.  Despite the name,
+it can be successfully combined with `--local` if you need that option.
++
+Note that this prevents things like `git push` from pushing LFS objects and
+locked files from being read only, since those are implemented by hooks.  If you
+need that functionality, you should review the Jenkins documentation about how
+to properly configure the environment in such a situation so that hooks can be
+used.
+
 == SEE ALSO
 
 git-config(1), git-lfs-install(1), gitattributes(5), gitignore(5).

docs/man/mangen.go

@@ -70,13 +70,15 @@ func main() {
 	out.WriteString("\t// THIS FILE IS GENERATED, DO NOT EDIT\n")
 	out.WriteString("\t// Use 'go generate ./commands' to update\n")
 	fileregex := regexp.MustCompile(`git-lfs(?:-([A-Za-z\-]+))?.adoc`)
-	headerregex := regexp.MustCompile(`^==\s+([A-Za-z0-9 ]+)`)
+	headerregex := regexp.MustCompile(`^(===?)\s+([A-Za-z0-9 -]+)`)
 	// cross-references
 	linkregex := regexp.MustCompile(`<<([^,>]+)(?:,([^>]+))?>>`)
 	// man links
 	manlinkregex := regexp.MustCompile(`(git)(?:-(lfs))?-([a-z\-]+)\(\d\)`)
 	// source blocks
 	sourceblockregex := regexp.MustCompile(`\[source(,.*)?\]`)
+	// anchors
+	anchorregex := regexp.MustCompile(`\[\[(.+)\]\]`)
 	count := 0
 	for _, f := range fs {
 		if match := fileregex.FindStringSubmatch(f.Name()); match != nil {
@@ -111,26 +113,31 @@ func main() {
 
 				// Special case headers
 				if hmatch := headerregex.FindStringSubmatch(line); hmatch != nil {
-					header := strings.ToLower(hmatch[1])
-					switch header {
-					case "name":
-						continue
-					case "synopsis":
-						// Ignore this, just go direct to command
-
-					case "description":
-						// Just skip the header & newline
-						skipNextLineIfBlank = true
-					case "options":
-						out.WriteString("Options:" + "\n")
-					case "see also":
-						// don't include any content after this
-						break scanloop
-					default:
-						out.WriteString(strings.ToUpper(header[:1]) + header[1:] + "\n")
-						out.WriteString(strings.Repeat("-", len(header)) + "\n")
+					if len(hmatch[1]) == 2 {
+						header := strings.ToLower(hmatch[2])
+						switch header {
+						case "name":
+							continue
+						case "synopsis":
+							// Ignore this, just go direct to command
+
+						case "description":
+							// Just skip the header & newline
+							skipNextLineIfBlank = true
+						case "options":
+							out.WriteString("Options:" + "\n")
+						case "see also":
+							// don't include any content after this
+							break scanloop
+						default:
+							out.WriteString(strings.ToUpper(header[:1]) + header[1:] + "\n")
+							out.WriteString(strings.Repeat("-", len(header)) + "\n")
+						}
+						firstHeaderDone = true
+					} else {
+						out.WriteString(hmatch[2] + "\n")
+						out.WriteString(strings.Repeat("~", len(hmatch[2])) + "\n")
 					}
-					firstHeaderDone = true
 					lastLineWasList = false
 					continue
 				}
@@ -155,6 +162,11 @@ func main() {
 					continue
 				}
 
+				if anchormatches := anchorregex.FindStringIndex(line); anchormatches != nil {
+					// Skip anchors.
+					continue
+				}
+
 				// Skip content until after first header
 				if !firstHeaderDone {
 					continue