From nobody Fri Oct 29 08:48:55 2021 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 8A8AE182FBD4 for ; Fri, 29 Oct 2021 08:48:55 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Hgbgq3YMCz4bLP; Fri, 29 Oct 2021 08:48:55 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4DC6B14450; Fri, 29 Oct 2021 08:48:55 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 19T8mtoP088282; Fri, 29 Oct 2021 08:48:55 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 19T8mtdd088281; Fri, 29 Oct 2021 08:48:55 GMT (envelope-from git) Date: Fri, 29 Oct 2021 08:48:55 GMT Message-Id: <202110290848.19T8mtdd088281@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Li-Wen Hsu Subject: git: 51d1d857fa - main - Porter's handbook: Mention git-format-patch(1) in using git to make patches List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: lwhsu X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 51d1d857fa76781b1875f920aa0c29c8c2c183b6 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by lwhsu: URL: https://cgit.FreeBSD.org/doc/commit/?id=51d1d857fa76781b1875f920aa0c29c8c2c183b6 commit 51d1d857fa76781b1875f920aa0c29c8c2c183b6 Author: Li-Wen Hsu AuthorDate: 2021-10-29 08:47:47 +0000 Commit: Li-Wen Hsu CommitDate: 2021-10-29 08:47:47 +0000 Porter's handbook: Mention git-format-patch(1) in using git to make patches Reviewed by: carlavilla, ygy, portmgr (bapt) Differential Revision: https://reviews.freebsd.org/D32485 Sponsored by: The FreeBSD Foundation --- .../books/porters-handbook/upgrading/_index.adoc | 33 ++++++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index b93d0dac18..968b25a6ed 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -113,11 +113,13 @@ Now that all of that is done, read about how to keep up-to-date in crossref:keep [[git-diff]] == Using Git to Make Patches -When possible, please submit a man:git[1] diff. +When possible, please submit a man:git[1] patch or diff. They are easier to handle than diffs between "new and old" directories. It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began, or if the committer asks for something to be fixed. -Also, a patch generated with `git diff` can be easily applied with `git apply` and will save some time to the committer. +Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer. +Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages. +These will be recorded in the log of the repository and this is the recommended way to submit your changes. [source,shell] .... @@ -159,12 +161,37 @@ Check the changes staged for the patch: % git diff --staged .... -The last step is to make a unified man:diff[1] of the changes: +The last step is to make an unified diff or patch of the changes: +To generate an unified diff with man:git-diff[1]: [source,shell] .... % git diff --staged > ../`make -VPKGNAME`.diff .... +This will generate a diff named like `foo-1.2.3.diff`. +Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message. + +To generate a patch with man:git-format-patch[1]: +[source,shell] +.... +% git checkout -b my_branch +% git commit +% git format-patch main +.... + +This will generate a patch named like `0001-foo.patch`. + +After patch has been created, you can switch to the main branch for starting other developments. +[source,shell] +.... +% git checkout main +.... + +Once the patch is accepted and merged, you can delete the local development branch if you want: +[source,shell] +.... +% git branch -D my_branch +.... [NOTE] ====