Bug 255323 - handbook: Discourage use of portsnap, document gitup
Summary: handbook: Discourage use of portsnap, document gitup
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-doc (Nobody)
URL:
Keywords: needs-patch
Depends on:
Blocks: 263315
  Show dependency treegraph
 
Reported: 2021-04-22 09:08 UTC by Mateusz Piotrowski
Modified: 2022-06-19 17:56 UTC (History)
9 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mateusz Piotrowski freebsd_committer 2021-04-22 09:08:32 UTC
portmgr suggests that we update the documentation so that it discourages the use of portsnap. As a substitute, we can document how to use gitup.

The reasoning behind discouraging the use of portsnap is:

portsnap is fragile, portmgr has had absolutely no success in having
things evolved for years, and while it was great in the old CVS times
where networks were flacky, and CVS was hard to use, there has been
better alternatives, with svn, there was svnup, and with git, there is
gitup.  Both use the repository directly, and don't require a third
party middleware.
Comment 1 Adam Weinberger freebsd_committer 2021-04-22 15:46:53 UTC
gitup works, but it's not the main thing we should be encouraging. People should use just plain git. We are in this weird cycle where we're recommending tool after tool to avoid just checking out the repo, when the simplest thing is just to check out the repo.
Comment 2 VVD 2021-04-23 12:24:35 UTC
gitup is useless - too slow.

On local SATA SSD:
[~]# time gitup ports
# Host: git.freebsd.org
# Port: 443
# Repository: /ports.git
# Target: /usr/ports
# Have: a2c5d69385fe0d8c5a666d570f5b464ca302d37d
# Want: a2c5d69385fe0d8c5a666d570f5b464ca302d37d
# Branch: main

real    2m58,839s
user    0m34,055s
sys     0m20,755s

On remote HDD via NFS:
[~]# time gitup ports
# Host: git.freebsd.org
# Port: 443
# Repository: /ports.git
# Target: /usr/ports
# Have: a2c5d69385fe0d8c5a666d570f5b464ca302d37d
# Want: a2c5d69385fe0d8c5a666d570f5b464ca302d37d
# Branch: main

real    22m28,088s
user    0m57,772s
sys     0m36,280s

Look at fields: "Have" = "Want", so it's just check without update.
Comment 3 Mathieu Arnold freebsd_committer 2021-04-26 07:32:19 UTC
The only reason I mentioned gitup is because people seem to be allergic to git, and it provided another way to access the repository, of course using git is better.
Comment 4 Graham Perrin 2021-12-02 14:01:44 UTC
(In reply to Mateusz Piotrowski from comment #0)

> … document how to use gitup. …

👍 please do. 

From line 1 at <https://cgit.freebsd.org/ports/tree/net/gitup/pkg-descr?id=c1e26e39b09d42f834f7c0d2ddad50c90b0a7ce6#n1>: 

>> … minimalist, dependency-free …
Comment 5 Graham Perrin 2021-12-02 14:04:45 UTC
(In reply to Adam Weinberger from comment #1)

> … git …

Use of git is already suitably documented in FreeBSD areas. 

In particular, the FreeBSD Foundation article linked (three options) from <https://old.reddit.com/comments/pfo6pc/-/>.
Comment 6 Graham Perrin 2021-12-02 14:34:44 UTC
(In reply to VVD from comment #2)

> gitup is useless 

Untrue. Too harsh. 


> too slow. 

Pros and cons of gitup, including the likelihood of inclusion in base, can be discussed in FreeBSD Forums, if you like. 

<https://forums.freebsd.org/posts/544851>: 

* an explanation for relative slowness when pulling

* a quote about future attention to disk performance. 

----

For now: 

* use of gitup is reasonably widespread

* the wish for documentation is reasonable.
Comment 7 PauAmma freebsd_triage 2021-12-02 15:31:59 UTC
(In reply to Adam Weinberger from comment #1)
"gitup works, but it's not the main thing we should be encouraging. People should use just plain git."

I strongly disagree. Git, like perl, is a Swiss Army chainsaw. (There's an interactive webpage that's there only to guide git users toward fixing mistakes they make using it.) A chainsaw with attached scalpels is the right tool if you need to amputate the hindleg of a live, kicking elephant near the hip and to do that fast. To butter my toast? Let me have a dull butter knife instead, please.
Comment 8 Steve Wills freebsd_committer 2021-12-02 16:32:10 UTC
(In reply to PauAmma from comment #7)

IMHO, the operations one needs to do with git are simple enough that adding the complexity of having the user choose and others support multiple tools is not worth it.

If you're only using vanilla ports and poudriere, I believe you can get ports and build packages without ever running git directly, instead having poudriere run it via "poudriere ports -c" and "poudriere ports -u". For anything past that, you're going to be making changes to ports and then need to use git proper in order to generate patches.

And to me, we should be able to provide packages that meet users needs without them having to build them themselves, which puts any package building into the realm of ports developers, but I know we're not there yet.
Comment 9 Graham Perrin 2021-12-04 07:59:10 UTC
This is a documentation bug for the FreeBSD Handbook. 


git
===

> Use of git is already suitably documented in FreeBSD areas. 

– including … drum roll … the Handbook. We have: 

<https://docs.freebsd.org/en/books/handbook/mirrors/#git>

> A.3. Using Git
> 
> … how to install Git on a FreeBSD system and use it to create a 
> local copy of a FreeBSD repository. Additional information on the 
> use of Git is included.


gitup and got
=============

Neither gitup nor Game of Trees (got) is mentioned in the Handbook. 

The wish to document gitup is consistent with tracking by the Git Migration Working Group. 

<https://www.freebsd.org/status/report-2021-07-2021-09/#_git_migration_working_group>
Comment 10 Muhammad Moinur Rahman freebsd_committer 2022-06-19 16:30:54 UTC
Whether we will use gitup as the next tool or not I think is a different question. But I want to stop encouraging portsnap at least. I maintain quite a number of ports and often have to deal with mails(not bugs) where users are using portsnap and have somewhat a broken tree. Switching to a git clone simply fixes the problem. I have also created and submitted a bug #263315 for this purpose. I am not against gitup but unless it's in the base it doesn't make any sense. We will need something else to get the ports tree to build itself.
Comment 11 Muhammad Moinur Rahman freebsd_committer 2022-06-19 16:32:24 UTC
(In reply to Muhammad Moinur Rahman from comment #10)
Oops sorry the bug #264763.
Comment 12 PauAmma freebsd_triage 2022-06-19 17:22:59 UTC
(In reply to Muhammad Moinur Rahman from comment #10)
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264763#c2
Comment 13 VVD 2022-06-19 17:47:49 UTC
Add git ("git-lite"?) to base or keep portsnap as default tool for ports.
gitup is extremely slow - useless in real use, git isn't in base yet.
Comment 14 Muhammad Moinur Rahman freebsd_committer 2022-06-19 17:56:39 UTC
(In reply to VVD from comment #13)
By the by I think everyone is missing a point here. This is not about removing portsnap from the base neither adding gitup/got in the base. And git/git-lite is never going to be landed in the base as the code is GPLv2.

The entire purpose of this is to discourage usage of portsnap. Just consider that when someone is planning to migrate to FreeBSD from Linux. And for port installation they are trying portsnap and somehow while portsnap fetch update it pollutes the tree making the tree unusable. Do you think that a new user will be interested with continuing with FreeBSD. No. That is the main purpose. People who are regular user and know about this will continue using it. If broken they know how to fix it. But a newbie in the FreeBSD world might not know about it and might lose interest sooner than ever.