diff options
Diffstat (limited to 'third_party/git/Documentation/MyFirstContribution.txt')
| -rw-r--r-- | third_party/git/Documentation/MyFirstContribution.txt | 101 |
1 files changed, 9 insertions, 92 deletions
diff --git a/third_party/git/Documentation/MyFirstContribution.txt b/third_party/git/Documentation/MyFirstContribution.txt index 427274df4d92..f8670379c0cf 100644 --- a/third_party/git/Documentation/MyFirstContribution.txt +++ b/third_party/git/Documentation/MyFirstContribution.txt @@ -23,42 +23,6 @@ useful additional context: - `Documentation/SubmittingPatches` - `Documentation/howto/new-command.txt` -[[getting-help]] -=== Getting Help - -If you get stuck, you can seek help in the following places. - -==== git@vger.kernel.org - -This is the main Git project mailing list where code reviews, version -announcements, design discussions, and more take place. Those interested in -contributing are welcome to post questions here. The Git list requires -plain-text-only emails and prefers inline and bottom-posting when replying to -mail; you will be CC'd in all replies to you. Optionally, you can subscribe to -the list by sending an email to majordomo@vger.kernel.org with "subscribe git" -in the body. The https://lore.kernel.org/git[archive] of this mailing list is -available to view in a browser. - -==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] - -This mailing list is targeted to new contributors and was created as a place to -post questions and receive answers outside of the public eye of the main list. -Veteran contributors who are especially interested in helping mentor newcomers -are present on the list. In order to avoid search indexers, group membership is -required to view messages; anyone can join and no approval is required. - -==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode - -This IRC channel is for conversations between Git contributors. If someone is -currently online and knows the answer to your question, you can receive help -in real time. Otherwise, you can read the -https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see -whether someone answered you. IRC does not allow offline private messaging, so -if you try to private message someone and then log out of IRC, they cannot -respond to you. It's better to ask your questions in the channel so that you -can be answered if you disconnect and so that others can learn from the -conversation. - [[getting-started]] == Getting Started @@ -74,26 +38,6 @@ $ git clone https://github.com/git/git git $ cd git ---- -[[dependencies]] -=== Installing Dependencies - -To build Git from source, you need to have a handful of dependencies installed -on your system. For a hint of what's needed, you can take a look at -`INSTALL`, paying close attention to the section about Git's dependencies on -external programs and libraries. That document mentions a way to "test-drive" -our freshly built Git without installing; that's the method we'll be using in -this tutorial. - -Make sure that your environment has everything you need by building your brand -new clone of Git from the above step: - ----- -$ make ----- - -NOTE: The Git build is parallelizable. `-j#` is not included above but you can -use it as you prefer, here and elsewhere. - [[identify-problem]] === Identify Problem to Solve @@ -153,8 +97,8 @@ int cmd_psuh(int argc, const char **argv, const char *prefix) ---- We'll also need to add the declaration of psuh; open up `builtin.h`, find the -declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, -in order to keep the declarations alphabetically sorted: +declaration for `cmd_push`, and add a new line for `psuh` immediately before it, +in order to keep the declarations sorted: ---- int cmd_psuh(int argc, const char **argv, const char *prefix); @@ -179,7 +123,7 @@ int cmd_psuh(int argc, const char **argv, const char *prefix) } ---- -Let's try to build it. Open `Makefile`, find where `builtin/pull.o` is added +Let's try to build it. Open `Makefile`, find where `builtin/push.o` is added to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in alphabetical order. Once you've done so, move to the top-level directory and build simply with `make`. Also add the `DEVELOPER=1` variable to turn on @@ -194,6 +138,9 @@ NOTE: When you are developing the Git project, it's preferred that you use the `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn it off, but it's a good idea to mention the problem to the mailing list. +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + Great, now your new command builds happily on its own. But nobody invokes it. Let's change that. @@ -202,7 +149,7 @@ a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string with the command name, a function pointer to the command implementation, and a setup option flag. For now, let's keep mimicking `push`. Find the line where `cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new -line in alphabetical order (immediately before `cmd_pull`). +line in alphabetical order. The options are documented in `builtin.h` under "Adding a new built-in." Since we hope to print some data about the user's current workspace context later, @@ -220,7 +167,7 @@ Check it out! You've got a command! Nice work! Let's commit this. `git status` reveals modified `Makefile`, `builtin.h`, and `git.c` as well as untracked `builtin/psuh.c` and `git-psuh`. First, let's take care of the binary, -which should be ignored. Open `.gitignore` in your editor, find `/git-pull`, and +which should be ignored. Open `.gitignore` in your editor, find `/git-push`, and add an entry for your new command in alphabetical order: ---- @@ -587,28 +534,6 @@ you want to pass as a parameter something which would usually be interpreted as a flag.) `parse_options()` will terminate parsing when it reaches `--` and give you the rest of the options afterwards, untouched. -Now that you have a usage hint, you can teach Git how to show it in the general -command list shown by `git help git` or `git help -a`, which is generated from -`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' -line above it in alphabetical order. Now, we can add some attributes about the -command which impacts where it shows up in the aforementioned help commands. The -top of `command-list.txt` shares some information about what each attribute -means; in those help pages, the commands are sorted according to these -attributes. `git psuh` is user-facing, or porcelain - so we will mark it as -"mainporcelain". For "mainporcelain" commands, the comments at the top of -`command-list.txt` indicate we can also optionally add an attribute from another -list; since `git psuh` shows some information about the user's workspace but -doesn't modify anything, let's mark it as "info". Make sure to keep your -attributes in the same style as the rest of `command-list.txt` using spaces to -align and delineate them: - ----- -git-prune-packed plumbingmanipulators -git-psuh mainporcelain info -git-pull mainporcelain remote -git-push mainporcelain remote ----- - Build again. Now, when you run with `-h`, you should see your usage printed and your command terminated before anything else interesting happens. Great! @@ -821,14 +746,6 @@ will automatically run your PRs through the CI even without the permission given but you will not be able to `/submit` your changes until someone allows you to use the tool. -NOTE: You can typically find someone who can `/allow` you on GitGitGadget by -either examining recent pull requests where someone has been granted `/allow` -(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: -is:pr is:open "/allow"]), in which case both the author and the person who -granted the `/allow` can now `/allow` you, or by inquiring on the -https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode -linking your pull request and asking for someone to `/allow` you. - If the CI fails, you can update your changes with `git rebase -i` and push your branch again: @@ -1053,7 +970,7 @@ reviewers the changes you've made that may not be as visible. You will also need to go and find the Message-Id of your previous cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the -https://lore.kernel.org/git[mailing list]. Find your cover letter in the +https://public-inbox.org/git[mailing list]. Find your cover letter in the archives, click on it, then click "permalink" or "raw" to reveal the Message-Id header. It should match: |