Reducing the depth of git pull

[yklaxds_gmail.com]

Summary

Reducing the depth of git pull in ports.

see also https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=272009

[fernape]

I'm not sure about this. This limits the log history to the last commit.
This section starts with the following sentence:

If more control over the ports tree is needed or if local changes need to be maintained, or if running FreeBSD-CURRENT...

I would say having the whole history is important if you want more control or need to keep local changes.

That said, I think that paragraph needs rephrasing. It mentions more than one method to install the ports collection yet it describes only one: the git method.

We should here, or in a different review:

• Change the sentence If it was not installed during the installation of FreeBSD, use one of the following methods to install it: to If it was not installed during the installation of FreeBSD, use the following method to install it:
• When doing the git clone, specify something like if you don't need complete control over the ports collection and you don't keep local changes, you can add --depth=1 as shown below

[carlavilla]

@imp can you please help us with this review?

[imp]

My take

documentation/content/en/books/handbook/ports/_index.adoc

714–717

Here, I'd add:

If you have your own changes to the ports tree, or need the history for any reason, omit the --depth 1 argument below.
It's faster for most situations,.

[fernape]

[emaste]

I think we might want to extend this in the future but this is a decent incremental improvement for most users.

documentation/content/en/books/handbook/ports/_index.adoc

714–717

There's some ambiguity so I would clarify the "It" in the second sentence - it could be taken as "omitting the --depth 1 argument is faster for most situations."

Something like

We add --depth 1 to the git command line to clone the tree without obtaining the commit history, which saves time and is acceptable for most users. If you have your own changes to the ports tree, or need the history for any reason, omit the --depth 1 argument below.

[carlavilla]

@imp @delphij is this review ok with the last changes?

[bcr]

I'll take care of committing this change soon.

[bcr]

Committed in https://cgit.freebsd.org/doc/commit/?id=cbe1572983c139a36fb0357e16df0dd01e1318ad
Forgot to reference this review and the PR. Will close the latter separately.
Thanks to everyone who provided input here.