Difference between revisions of "Use of Git"

Latest revision as of 01:32, 20 April 2017

Note: This is a superset of the information at https://www.openssl.org/source/gitrepo.html

Background information about using the Git distributed version control system[edit]

This page provides examples for some of the git commands used when accessing OpenSSL source code, but does not provide complete coverage.

Refer to the git man ages and http://git-scm.com/ for more complete instructions on using the command.
Refer to https://github.com/ for more complete instructions on interacting with Github.

Use of Git with OpenSSL source tree[edit]

The OpenSSL group hosts its own Git repository at openssl.org, and this contains the master copy of OpenSSL. You can browse this at https://git.openssl.org/gitweb/?p=openssl.git;a=tree, or get a clone (checkout) of it with the command git clone git://git.openssl.org/openssl.git.

Contributors to OpenSSL should make use of the Github copy of this repository at https://github.com/openssl/openssl. Github makes it easy to maintain your own fork of OpenSSL for developing your contributions, as well as making a "pull request" to share fixes with the OpenSSL team when finished. Changes in the master Git repository are represented in the Github copy within minutes.

You can view existing pull requests against any of the branches at https://github.com/openssl/openssl/pulls

Getting a copy of the OpenSSL source tree[edit]

If you want to quickly make a copy of the OpenSSL source tree and you do not plan to publish any changes for use by others, just create a clone on your own machine.

$ git clone https://github.com/openssl/openssl.git

(Refer to Github documentation for instructions on other means of cloning the source tree.)

If you plan to make changes to the sources that you will share with others, including contributing changes to OpenSSL, it is recommended that you create a fork of the OpenSSL tree using your own Github id. You can use this to share changes with others whether or not you intend to submit changes to the OpenSSL team. Refer to the documentation at https://help.github.com/articles/fork-a-repo, in particular the discussion about how to track changes in the real OpenSSL repository that you forked.

Branches[edit]

The Git repositories contain multiple branches, representing development levels of OpenSSL as well as current and upcoming stable branches. An easy way to see the available branches is with the branch selector at https://github.com/openssl/openssl. The branches which are of most interest to most users are

master (development)
OpenSSL_1_1_0-stable
OpenSSL_1_0_2-stable

In order to access the code for a branch other than master, clone the Git repository then use the git checkout branchname command to switch to a different branch. Consider using separate checkouts for each branch you are working in, with appropriate names for each, such as in the following example.

$ git clone https://github.com/openssl/openssl.git OpenSSL-master
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_1_0-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_1_0-stable)
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_2-stable)

If you've created your own fork of OpenSSL, replace the URL on the git clone command with the one for your fork. Also, you'll need to follow the instructions at https://help.github.com/articles/fork-a-repo for picking up changes from the master repository that you forked.

Making pull requests[edit]

After developing and testing changes to OpenSSL in your checkout (clone), push them to your fork of OpenSSL (git push), then use the Github interface to submit a pull request to the master OpenSSL repository for the particular revision(s).

Anyone can comment on PR's, and suggest changes. Before a PR is accepted, it must be approved by two OpenSSL team members.

Use of Git with the OpenSSL web site[edit]

The OpenSSL web site is also maintained in git, and can be browsed at https://git.openssl.org/gitweb/?p=openssl-web.git;a=tree.

Unlike the source code, the OpenSSL web site repository is not copied to Github. You can only interact with it via git.openssl.org, so it is not possible to submit pull requests.

Check it out as follows:

$ git clone git://git.openssl.org/openssl-web.git

In order to submit corrections to the web site, create a patch as described above.

Only the master branch of the web site repository is used.

@@ Line 1: / Line 1: @@
-Note: This is a superset of the information at http://www.openssl.org/source/repos.html
+Note: This is a superset of the information at https://www.openssl.org/source/gitrepo.html
 == Background information about using the Git distributed version control system ==
@@ Line 33: / Line 33: @@
 * master (development)
-* OpenSSL_1_0_2-stable (for the not-yet-released 1.0.2 series)
+* OpenSSL_1_1_0-stable
-* OpenSSL_1_0_1-stable
+* OpenSSL_1_0_2-stable
-* OpenSSL_1_0_0-stable
 In order to access the code for a branch other than master, clone the Git repository then use the <tt>git checkout ''branchname''</tt> command to switch to a different branch.  Consider using separate checkouts for each branch you are working in, with appropriate names for each, such as in the following example.
@@ Line 41: / Line 40: @@
 <pre>
 $ git clone https://github.com/openssl/openssl.git OpenSSL-master
+$ git clone https://github.com/openssl/openssl.git OpenSSL_1_1_0-stable
+$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_1_0-stable)
 $ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable
 $ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_2-stable)
-$ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_1-stable
-$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_1-stable)
 </pre>
 If you've created your own fork of OpenSSL, replace the URL on the <tt>git clone</tt> command with the one for your fork.  Also, you'll need to follow the instructions at https://help.github.com/articles/fork-a-repo for picking up changes from the master repository that you forked.
-=== Making patches ===
-Patches posted to OpenSSL development mailing lists or to the [https://www.openssl.org/support/rt.html OpenSSL Request Tracker] should be in Git <tt>format-patch</tt> format if at all practical, since that is easier for OpenSSL committers to apply since it contains author details.
-The [http://git-scm.com/docs/git-format-patch <tt>git format-patch</tt>] documentation describes a lot of options.  Here is an example of the most basic use.
-:* You've been working on a particular OpenSSL branch within a Git clone of the source tree, and have made a couple of commits which you'd like to submit.
-:* Print the log for those two commits and one more, the one before your commits:
-<pre>
-$ git log -3
-commit 46983b73e04b448cb6cd9ea180044753174dec6d
-Author: Jeff Trawick <trawick@gmail.com>
-Date:   Fri Apr 25 20:25:19 2014 -0400
-    spellcheck
-commit 1e20bdf6bad38d9766e6cf3e64d903a99f1d9a6b
-Author: Jeff Trawick <trawick@gmail.com>
-Date:   Fri Apr 25 14:07:07 2014 -0400
-    silly wording change
-commit 3e124d66c8b66a48a824387b10768411a348f518
-Author: Steve Marquess <marquess@opensslfoundation.com>
-Date:   Thu Apr 24 07:13:05 2014 -0400
-    Add new sponsors
-    (cherry picked from commit 351f0a124bffaa94d2a8abdec2e7dde5ae9c457d)
-</pre>
-:* Create a patch from changes '''after''' the third commit (<tt>3e124d66c8b66a48a824387b10768411a348f518</tt>), and pipe it to a file instead of letting <tt>git</tt> create a bunch of <tt>.patch</tt> files in the current directory:
-<pre>
-$ git format-patch 3e124d66c8b66a48a824387b10768411a348f518 --stdout >/tmp/FixWording.txt
-$ cat /tmp/FixWording.txt
-From 1e20bdf6bad38d9766e6cf3e64d903a99f1d9a6b Mon Sep 17 00:00:00 2001
-From: Jeff Trawick <trawick@gmail.com>
-Date: Fri, 25 Apr 2014 14:07:07 -0400
-Subject: [PATCH 1/2] silly wording change
----
- apps/s_client.c | 2 +-
-file changed, 1 insertion(+), 1 deletion(-)
-diff --git a/apps/s_client.c b/apps/s_client.c
-index 01f4f34..eeb2e77 100644
---- a/apps/s_client.c
-+++ b/apps/s_client.c
-@@ -323,7 +323,7 @@ static void sc_usage(void)
- 	BIO_printf(bio_err,"\n");
- 	BIO_printf(bio_err," -host host     - use -connect instead\n");
- 	BIO_printf(bio_err," -port port     - use -connect instead\n");
--	BIO_printf(bio_err," -connect host:port - who to connect to (default is %s:%s)\n",SSL_HOST_NAME,PORT_STR);
-+	BIO_printf(bio_err," -connect host:port - what to connect to (default is %s:%s)\n",SSL_HOST_NAME,PORT_STR);
- 	BIO_printf(bio_err," -checkhost host - check peer certificate matches \"host\"\n");
- 	BIO_printf(bio_err," -checkemail email - check peer certificate matches \"email\"\n");
- 	BIO_printf(bio_err," -checkip ipaddr - check peer certificate matches \"ipaddr\"\n");
---
-.8.3.2
-From 46983b73e04b448cb6cd9ea180044753174dec6d Mon Sep 17 00:00:00 2001
-From: Jeff Trawick <trawick@gmail.com>
-Date: Fri, 25 Apr 2014 20:25:19 -0400
-Subject: [PATCH 2/2] spellcheck
----
- PROBLEMS | 6 +++---
-file changed, 3 insertions(+), 3 deletions(-)
-diff --git a/PROBLEMS b/PROBLEMS
-index 3eaab01..86f1e6e 100644
---- a/PROBLEMS
-+++ b/PROBLEMS
-@@ -41,13 +41,13 @@ passing -Wl,-search_paths_first, but it's unknown if the flag was
- supported from the initial MacOS X release.
--* Parallell make leads to errors
-+* Parallel make leads to errors
--While running tests, running a parallell make is a bad idea.  Many test
-+While running tests, running a parallel make is a bad idea.  Many test
- scripts use the same name for output and input files, which means different
- will interfere with each other and lead to test failure.
--The solution is simple for now: don't run parallell make when testing.
-+The solution is simple for now: don't run parallel make when testing.
- * Bugs in gcc triggered
---
-.8.3.2
-</pre>
-Plan B, if you can't get <tt>git format-patch</tt> to work for some reason, is to create another, unmodified clone of the OpenSSL code, switch it to the branch you're working in, then use <tt>diff -ru</tt> as follows:
-<pre>
-$ diff -ru OpenSSL_1_0_2-stable-original OpenSSL_1_0_2-stable > /tmp/FixSClientUsage.txt
-</pre>
-(These two directories were created with <tt>git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable</tt> and <tt>git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable-original</tt>, and each was switched to the desired branch with <tt>git checkout OpenSSL_1_0_2-stable</tt>.)
-Double check that only the desired changes are in the patch file.  Otherwise, you probably weren't testing with the most recent OpenSSL changes.
-==== Sending patches via e-mail ====
-Patches sent via e-mail should be in plain text attachments instead of being pasted into the e-mail body.
 === Making pull requests ===
@@ Line 160: / Line 52: @@
 After developing and testing changes to OpenSSL in your checkout (clone), push them to your fork of OpenSSL (<tt>git push</tt>), then use the Github interface to submit a pull request to the master OpenSSL repository for the particular revision(s).
-(need to allude to other instructions about RT, right?)
+Anyone can comment on PR's, and suggest changes.  Before a PR is accepted, it must be approved by two OpenSSL team members.
 == Use of Git with the OpenSSL web site ==

Difference between revisions of "Use of Git"

Latest revision as of 01:32, 20 April 2017

Contents

Background information about using the Git distributed version control system[edit]

Use of Git with OpenSSL source tree[edit]

Getting a copy of the OpenSSL source tree[edit]

Branches[edit]

Making pull requests[edit]

Use of Git with the OpenSSL web site[edit]

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools