Date: Sat, 17 Apr 2021 19:36:36 GMT From: Mateusz Piotrowski <0mp@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 84d56d3868 - main - Capitalize words properly Message-ID: <202104171936.13HJaaQq081487@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/doc/commit/?id=84d56d3868a699c64c51d7453cedab0f3468ba03 commit 84d56d3868a699c64c51d7453cedab0f3468ba03 Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2021-04-17 19:33:58 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2021-04-17 19:33:58 +0000 Capitalize words properly I've capitalized "git" throughout the document where appropriate. There are also some other words I've fixed like "github" and "gitlab", but I've not reviewed the whole document looking for those. --- .../en/articles/committers-guide/_index.adoc | 88 +++++++++++----------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 1c30db5528..bddc637464 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -283,9 +283,9 @@ It covers getting the sources, updating the sources, bisecting and touches brief It covers the basics, and tries to give good pointers to more in-depth treatment for when the reader finds the basics insufficient. Other sections of this guide cover more advanced topics related to contributing to the project. -The goal of this section is to highlight those bits of git needed to track sources. -They assume a basic understanding of git. -There are many primers for git on the web, but the https://git-scm.com/book/en/v2[Git Book] provides one of the better treatments. +The goal of this section is to highlight those bits of Git needed to track sources. +They assume a basic understanding of Git. +There are many primers for Git on the web, but the https://git-scm.com/book/en/v2[Git Book] provides one of the better treatments. ==== Keeping Current With The FreeBSD src Tree [[keeping_current]] @@ -296,11 +296,11 @@ Most people will want to do a deep clone of the repository. However, there are times when you may wish to do a shallow clone. ===== Branch names -The branch names in the new git repository are similar to the old names. +The branch names in the new Git repository are similar to the old names. For the stable branches, they are stable/X where X is the major release (like 11 or 12). The main branch in the new repository is 'main'. The main branch in the old GitHub mirror was 'master', but is now 'main'. -Both reflect the defaults of git at the time they were created. +Both reflect the defaults of Git at the time they were created. The 'main' branch is the default branch if you omit the '-b branch' or '--branch branch' options below. ===== Repositories @@ -313,7 +313,7 @@ How we track changes in third-party applications is discussed elsewhere and gene ===== Deep Clone A deep clone pulls in the entire tree, as well as all the history and branches. It is the easiest to do. -It also allows you to use git's worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository. +It also allows you to use Git's worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository. [source,shell] .... % git clone -o freebsd $URL -b branch [dir] @@ -365,7 +365,7 @@ eg: so that won't be covered in depth here. If you want to build a custom kernel, link:{handbook}#kernelconfig[the kernel config section] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. -To have MYKERNEL disregarded by git, it can be added to .git/info/exclude. +To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude. ===== Updating @@ -376,7 +376,7 @@ This pulls in all the revisions since your last update. % git pull --ff-only .... will update the tree. -In git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits. +In Git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits. By always doing a 'fast forward' merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree. This will be important if you want to maintain local patches. @@ -385,7 +385,7 @@ The simplest is to use --autostash on the 'git pull' command, but more sophistic ==== Selecting a Specific Version -In git, the 'git checkout' checks out both branches and specific versions. +In Git, the 'git checkout' checks out both branches and specific versions. Git's versions are the long hashes rather than a sequential number. When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want): @@ -441,7 +441,7 @@ a8163e165c5b (upstream/master) HEAD@{1}: checkout: moving from b6fb97efb682994f5 .... shows me moving the working tree to the master branch (a816...) and then updating from upstream (to 5ef0...). In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. -As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your git tree after updating, but before you discover the need to bisect. +As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your Git tree after updating, but before you discover the need to bisect. ==== Set the 'good' version first, then set the bad (though the order doesn't matter). @@ -468,7 +468,7 @@ The ports tree operates the same way. The branch names are different and the repositories are in different locations. The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ . -The production git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). +The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). There is also a mirror on GitHub, see link:{handbook}mirrors/#mirrors[Exteral mirrors] for an overview. The 'current' branch is 'main' . @@ -479,7 +479,7 @@ This section addresses tracking local changes. If you have no local changes, you can stop reading now (it is the last section and OK to skip). One item that is important for all of them: all changes are local until pushed. -Unlike svn, git uses a distributed model. +Unlike Subversion, Git uses a distributed model. For users, for most things, there is very little difference. However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD. All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this). @@ -498,13 +498,13 @@ Stashing is also integrated with the 'git pull' command: just add '--autostash' ===== Keeping a local branch [[keeping_a_local_branch]] -It is much easier to keep a local branch with git than subversion. +It is much easier to keep a local branch with Git than Subversion. In subversion you need to merge the commit, and resolve the conflicts. This is manageable, but can lead to a convoluted history that's hard to upstream should that ever be necessary, or hard to replicate if you need to do so. Git also allows one to merge, along with the same problems. That's one way to manage the branch, but it's the least flexible. -In addition to merging, git supports the concept of 'rebasing' which avoids these issues. +In addition to merging, Git supports the concept of 'rebasing' which avoids these issues. The 'git rebase' command replays all the commits of a branch at a newer location on the parent branch. We will cover the most common scenarios that arise using it. @@ -513,7 +513,7 @@ We will cover the most common scenarios that arise using it. Let's say you want to make a change to FreeBSD's ls command to never, ever do color. There are many reasons to do this, but this example will use that as a baseline. The FreeBSD ls command changes from time to time, and you'll need to cope with those changes. -Fortunately, with git rebase it usually is automatic. +Fortunately, with Git rebase it usually is automatic. [source,shell] .... % cd src @@ -539,16 +539,16 @@ index 7378268867ef..cfc3f4342531 100644 .... The commit will pop you into an editor to describe what you've done. -Once you enter that, you have your own **local** branch in the git repo. +Once you enter that, you have your own **local** branch in the Git repo. Build and install it like you normally would, following the directions in the handbook. -git differs from other version control systems in that you have to tell it explicitly which files to commit. +Git differs from other version control systems in that you have to tell it explicitly which files to commit. I have opted to do it on the commit command line, but you can also do it with 'git add' which many of the more in depth tutorials cover. ====== Time to update When it is time to bring in a new version, it is almost the same as w/o the branches. You would update like you would above, but there is one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. -It is important to start rebasing operations with a clean tree (git usually requires this). +It is important to start rebasing operations with a clean tree (Git usually requires this). [source,shell] .... @@ -559,7 +559,7 @@ It is important to start rebasing operations with a clean tree (git usually requ This will bring up an editor that lists all the commits in it. For this example, do not change it at all. -This is typically what you are doing while updating the baseline (though you also use the git rebase command to curate the commits you have in the branch). +This is typically what you are doing while updating the baseline (though you also use the Git rebase command to curate the commits you have in the branch). Once you are done with the above, you have to move the commits to ls.c forward from the old version of FreeBSD to the newer one. @@ -612,7 +612,7 @@ The rebase was interrupted, so you have to complete it: % git rebase --continue .... -which tells git that ls.c has been fixed and to continue the rebase operation. +which tells Git that ls.c has been fixed and to continue the rebase operation. Since there was a conflict, you will get kicked into the editor to update the commit message if necessary. If the commit message is still accurate, just exit the editor. @@ -649,8 +649,8 @@ Then you rebase onto the main branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a place holder name). -===== Migrating from an existing git clone -If you have work based on a previous git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because git has no knowledge about the connection between the two. +===== Migrating from an existing Git clone +If you have work based on a previous Git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because Git has no knowledge about the connection between the two. When you have only a few local changes, the easiest way would be to cherry-pick those changes to the new base: [source,shell] @@ -818,10 +818,10 @@ With subversion, we used the following practices to achieve these goals: * Recording mergeinfo so that `svn mergeinfo --show-revs` worked. With Git, we will need to use different strategies to achieve the same goals. -This document aims to define best practices when merging source commits using git that achieve these goals. -In general, we aim to use git's native support to achieve these goals rather than enforcing practices built on subversion's model. +This document aims to define best practices when merging source commits using Git that achieve these goals. +In general, we aim to use Git's native support to achieve these goals rather than enforcing practices built on subversion's model. -One general note: due to technical differences with Git, we will not be using git "merge commits" (created via `git merge`) in stable or releng branches. +One general note: due to technical differences with Git, we will not be using Git "merge commits" (created via `git merge`) in stable or releng branches. Instead, when this document refers to "merge commits", it means a commit originally made to `main` that is replicated or "landed" to a stable branch, or a commit from a stable branch that is replicated to a releng branch with some variation of `git cherry-pick`. ==== Finding Eligible Hashes to MFC @@ -1141,7 +1141,7 @@ All vendor branches and tags start with `vendor/`. These branches and tags are v [NOTE] ==== -This chapter follows the convention that the `freebsd` origin is the origin name for the official FreeBSD git repository. +This chapter follows the convention that the `freebsd` origin is the origin name for the official FreeBSD Git repository. If you use a different convention, replace `freebsd` with the name you use instead in the examples below. ==== @@ -1262,7 +1262,7 @@ Examine the tree against `merge_result` to make sure that you haven't missed del ==== Pushing the changes -Once you are sure that you have a set of deltas you think is good, you can push it to a fork off github or gitlab for others to review. +Once you are sure that you have a set of deltas you think is good, you can push it to a fork off GitHub or GitLab for others to review. One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. While phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. @@ -1383,10 +1383,10 @@ This section is designed to walk people through the conversion process from Subv ==== Migrating from a Subversion tree -This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source git repo. +This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source Git repo. The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production. -The first thing to do is install git. Any version of Git will do, though the latest one in ports / packages generally will be good. +The first thing to do is install Git. Any version of Git will do, though the latest one in ports / packages generally will be good. Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`): [source,shell] @@ -1408,10 +1408,10 @@ First, let's clone the repository: will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions. We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well. -https://github.com/freebsd/freebsd-legacy.git has the old github mirror with the old hashes should you need that for your migration. -The github `master` branch has been frozen. -As the default in git has changed, we've shifted from `master` to `main`; the new repository uses `main`. -We also mirror the repository to gitlab at https://gitlab.com/FreeBSD/src.git . +https://github.com/freebsd/freebsd-legacy.git has the old GitHub mirror with the old hashes should you need that for your migration. +The GitHub `master` branch has been frozen. +As the default in Git has changed, we've shifted from `master` to `main`; the new repository uses `main`. +We also mirror the repository to GitLab at https://gitlab.com/FreeBSD/src.git . It's useful to have the old Subversion revisions available. This data is stored using Git notes, but Git doesn't fetch those by default. @@ -1578,8 +1578,8 @@ Note: as of this writing, https://github.com/freebsd/freebsd-src is mirroring al The `master` branch will not be updated anymore, and the link:https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf[last commit] contains the instructions for migrating to the new `main` branch. We'll retain the `master` branch for a certain time, but in the future it will only be kept in the link:https://github.com/freebsd/freebsd-legacy[freebsd-legacy] repository. -When migrating branches from a github fork from the old github mirror to the official repo, the process is straight forward. -This assumes that you have a `freebsd` upstream pointing to github, adjust if necessary. +When migrating branches from a GitHub fork from the old GitHub mirror to the official repo, the process is straight forward. +This assumes that you have a `freebsd` upstream pointing to GitHub, adjust if necessary. This also assumes a clean tree before starting... ===== Add the new `freebsd` upstream repository: @@ -1614,7 +1614,7 @@ You'll need to do the following once to update the push URL if you are a FreeBSD (note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.) You will also need to add `freebsd` as the location to push to. -The author recommends that your upstream github repository remain the default push location so that you only push things into FreeBSD you intend to by making it explicit. +The author recommends that your upstream GitHub repository remain the default push location so that you only push things into FreeBSD you intend to by making it explicit. [[git-faq]] === Git FAQ @@ -1855,7 +1855,7 @@ To fix your `main` branch, just make it point to the remote's `main`: git branch -f main freebsd/main .... -There's nothing magical about branches in git: they are just labels on a graph that are automatically moved forward by making commits. +There's nothing magical about branches in Git: they are just labels on a graph that are automatically moved forward by making commits. So the above works because you're just moving a label. There's no metadata about the branch that needs to be preserved due to this. @@ -1959,7 +1959,7 @@ and use the `git rebase -i` to fold the related commits together). ==== Cloning and Mirroring -**Q:** I'd like to mirror the entire git repository, how do I do that? +**Q:** I'd like to mirror the entire Git repository, how do I do that? **A:** If all you want to do is mirror, then @@ -2025,11 +2025,11 @@ would look at the log for the vendor branch for zlib starting at 1.2.10. === Collaborating with others One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree. -The FreeBSD project's git repositories do not, yet, allow user created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user generated branch. +The FreeBSD project's Git repositories do not, yet, allow user created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user generated branch. The following instructions show how to set up a user generated branch, based on the FreeBSD main branch, and push it to GitHub. -Before you begin, make sure that your local git repo is up to date and has the correct origins set <<keeping_current,as shown above.>> +Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>> [source,shell] ```` @@ -2059,7 +2059,7 @@ With this in place you can create a branch <<keeping_a_local_branch,as shown abo .... Make whatever modifications you wish in your branch. Build, test, and once you're ready to collaborate with others it's time to push your changes into your hosted branch. -Before you can push you'll have to set the appropriate upstream, as git will tell you the first time you try to push to your +github+ remote: +Before you can push you'll have to set the appropriate upstream, as Git will tell you the first time you try to push to your +github+ remote: [source,shell] .... @@ -2431,7 +2431,7 @@ The subject should, by itself, allow the reader to quickly determine if the chan === Keep subject lines short The subject line should be as short as possible while still retaining the required information. -This is to make browsing git log more efficient, and so that git log --oneline can display the short hash and subject on a single 80-column line. +This is to make browsing Git log more efficient, and so that git log --oneline can display the short hash and subject on a single 80-column line. A good rule of thumb is to stay below 63 characters, and aim for about 50 or fewer if possible. === Prefix the subject line with a component, if applicable @@ -2529,7 +2529,7 @@ a mailing list. |`Submitted by:` |The name and e-mail address of the person that submitted the fix; for developers, just the username on the FreeBSD cluster. -Typically not used with git; in the src and doc trees submitted patches should +Typically not used with Git; in the src and doc trees submitted patches should have the author set by using `git commit --author` If the submitter is the maintainer of the port being committed, include "(maintainer)" after the email address. @@ -2572,7 +2572,7 @@ Approved by: re (username) |The name of the project (if any) from which the code was obtained. Do not use this line for the name of an individual person. |`Fixes:` -|The git short hash as returned by `git rev-parse --short` and the title line of a commit that is fixed by this change. +|The Git short hash as returned by `git rev-parse --short` and the title line of a commit that is fixed by this change. |`MFC after:` |To receive an e-mail reminder to MFC at a later date, specify the number of days, weeks, or months after which an MFC is planned.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104171936.13HJaaQq081487>