gitworkflow

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
gitworkflow [2015/04/22 22:17] – CraigRodriguesgitworkflow [2021/12/14 20:46] (current) – Since this is the top Google result, Give users half a chance of finding the official git repo and 'git clone' URI. DavidOBrien
Line 1: Line 1:
 +The official %%FreeBSD%% Git repo is now at https://cgit.freebsd.org/src/
 +
 +Clone TL;DR:
 +(public-mirror)
 +https://git.FreeBSD.org/src.git
 +ssh:%%//%%anongit@git.%%FreeBSD%%.org/src.git
 +(developers-only)
 +ssh:%%//%%git@gitrepo.%%FreeBSD%%.org/src.git
 +
 +The content of this page needs to be updated, please refer to the latest doc from git migration WG at https://github.com/bsdimp/freebsd-git-docs/ , and the discussion on https://lists.freebsd.org/mailman/listinfo/freebsd-git .
 +
 +Update: 2020-12-14: These are not the repositories for the 2020/2021 svn to git conversion, please see the note above. The below is mostly historic information and will soon be entirely obsolete.
 +
 ====== Introduction ====== ====== Introduction ======
  
-There are a couple of %%FreeBSD%% git repositories that have been converted with +This page used to describe the inofficial git mirrors of the SVN repositories of the %%FreeBSD%% project that could be used as common repositories to
-various programs and various parameters. This page describes the "official" +
-git-branches of the %%FreeBSD%% project that should be used as common repositories to+
 base other work on. base other work on.
  
-The repositories are provided as a read-only mirror of the state of the Subversion +The repositories were read-only mirrors of the [[https://www.freebsd.org/doc/handbook/svn.html|src, doc and, ports FreeBSD Subversion repositories]]
-src, doc and, ports repositories at http://svn.FreeBSD.org/base, http://svn.FreeBSD.org/doc, and http://svn.FreeBSD.org/ports respectively. +
-Using git to commit changes to +
-these repositories is not officially supported (but doable), instead it is supposed to serve as +
-a collaboration point by using additional tools like Github, Gitorious, or +
-Gerrit, etc.+
  
-Bear in mind that git will not replace Subversion for use in %%FreeBSD%% and the +Bear in mind that git does not replace use of Subversion in %%FreeBSD%% and the 
-repository is only offered on a best-effort basis. The steps to redo the +repository is currently offered on a best-effort basis only. The steps to recreate the conversion are outlined below, so that people can replicate the process in-house should they wish to.
-conversion are outlined below, so that people can move the process in-house +
-should they see the need for it.+
  
-CAVEAT EMPTOR: It is possible (but highly unlikely) that the repositories might need to be re-done due to bugs in the converter.+CAVEAT EMPTOR: It is possible that the repositories might need to be re-done due to bugs in the converter.
 This would result in changed commit IDs for the impacted branches. This would result in changed commit IDs for the impacted branches.
 As the actual tree objects for a certain SVN revision will remain identical, it will always be possible to rebase or merge your work on these new branches and not run into any merge conflicts. As the actual tree objects for a certain SVN revision will remain identical, it will always be possible to rebase or merge your work on these new branches and not run into any merge conflicts.
 Advance notice will be provided if this proves necessary, along with advice on the required git commands. Advance notice will be provided if this proves necessary, along with advice on the required git commands.
  
-====== The Repositories ======+In fact, "bad SVN metadata" escaped into the published repos on github.com, so they **will** be re-rolled at some future date.
  
-The beta repository-mirrors are updated at least hourly, should they lag the svn repository by more than a day, please contact %%<%%uqs@%%FreeBSD%%.org> (monitoring still needs to be put into place, help wanted btw).+====== Repositories ======
  
-  * **[[https://github.com/freebsd/freebsd.git]]** +The repository mirrors are updated at least hourly. Should they lag the SVN repository by more than a day, please create a [[https://bugs.freebsd.org/bugzilla/enter_bug.cgi?component=Git%20Integration&product=Services|new Bugzilla Issue: Git Integration]]. Monitoring still needs to be put into place, help wanted btw.
-  * **[[https://github.com/freebsd/freebsd-doc.git]]** +
-  * **[[https://github.com/freebsd/freebsd-ports.git]]** (the preferred sources) +
-  * git:%%//%%git-beta.freebsd.org/freebsd-base.git +
-  * git:%%//%%git-beta.freebsd.org/freebsd-doc.git +
-  * git:%%//%%git-beta.freebsd.org/freebsd-ports.git (the canonical sources)+
  
-====== Known Problems ======+As of 2020-12-14, canonical repository of doc has been migrate to git:
  
-  * SVN merges for single revisions (that span only parts of the tree then), are not really representable as merges in git and instead are called cherry-picks there. The converter tries to be smart about whole tree merges however -- this heuristic is only activated for the head/, user/, and projects/ branches. A whole-tree merge of project/foo into head/ should thus be correctly represented in git. Merges from head/ to stable/ or from contrib/ to head/ will be plain commits, i.e. "cherry-picks".+  * https://cgit.freebsd.org/doc/ (web repository browser) 
 +  * ''%%https://git.FreeBSD.org/doc.git%%'' (readonly, geographically distributed mirror for cloning through https) 
 +  * anongit@git.%%FreeBSD%%.org:doc.git (readonly, geographically distributed mirror for cloning through anonymous ssh) 
 +  * git@gitrepo.%%FreeBSD%%.org:doc.git (read/write for committers to push) 
 + 
 +ports: 
 +  * **[[https://github.com/freebsd/freebsd-ports.git]]** (the preferred sources for cloning and browsing) 
 +  * https://cgit-beta.freebsd.org/ports/ (the canonical sources, web repository browser) 
 +  * ''%%https://cgit-beta.freebsd.org/ports.git%%'' (the canonical sources for cloning) 
 + 
 +src: 
 +  * **[[https://github.com/freebsd/freebsd.git]]** (the preferred sources for cloning and browsing) 
 +  * https://cgit-beta.freebsd.org/src/ (the canonical sources, web repository browser) 
 +  * ''%%https://cgit-beta.freebsd.org/src.git%%'' (the canonical sources for cloning)
  
 ====== Quick Start ====== ====== Quick Start ======
 +
 +  * Fork your own copy of https://github.com/freebsd/freebsd.git: [[https://help.github.com/articles/fork-a-repo/|Fork A Repo]]
 +  * Keep your fork in sync: [[https://help.github.com/articles/syncing-a-fork/|Syncing a fork]]
  
 <code> <code>
-$ git clone --config remote.origin.fetch='+refs/notes/*:refs/notes/*' git://github.com/freebsd/freebsd.git+$ git clone --config remote.origin.fetch='+refs/notes/*:refs/notes/*' https://github.com/YourGitUserName/freebsd.git
 $ cd freebsd && git pull   # For some reason, the notes will not be fetched during the clone operation ... $ cd freebsd && git pull   # For some reason, the notes will not be fetched during the clone operation ...
-$ hack, hack, hack+(hack, hack, hack)
 $ git commit $ git commit
 </code> </code>
Line 55: Line 70:
  
 See any other git howto or documentation if you're stuck on the basics. See any other git howto or documentation if you're stuck on the basics.
-A useful reference for the issue with notes is http://git-scm.com/2010/08/25/notes.html.+A useful reference for the issue with notes is [[https://git-scm.com/book/en/v2|Pro Git book, written by Scott Chacon and Ben Straub and published by Apress]].
  
 ===== Adding SVN Revision Notes to an Existing Clone ===== ===== Adding SVN Revision Notes to an Existing Clone =====
Line 75: Line 90:
  
 ====== Integration ====== ====== Integration ======
-===== Using git-svn (FreeBSD committers only) ===== 
  
-If you install the [[http://www.freshports.org/devel/git-subversion/|devel/git-subversion]] port, +===== Using git-svn =====
-you can use [[http://git-scm.com/docs/git-svn|git svn]] to push code back to a Subversion repository +
-from a git tree.+
  
-<code>+[[GitWorkflow/GitSvn#Using_git-svn|Using git-svn]]
  
-# for ports committers: +===== Merging pull requests from GitHub using git-svn =====
-$ GIT_REPO=git://github.com/freebsd/freebsd-ports.git +
-$ GIT_SVN_URI=svn.freebsd.org/ports+
  
-# for source committers: +Note: This only applies to, and works for committers
-$ GIT_REPO=git://github.com/freebsd/freebsd.git +
-$ GIT_SVN_URI=svn.freebsd.org/base+
  
-# do the cloning +[[GitWorkflow/GitSvn#Merging_pull_requests_from_github_using_git-svn_.28FreeBSD_committers_only.29|Merging pull requests from GitHub]]
-$ git clone $GIT_REPO freebsd +
-$ cd freebsd+
  
-# init git-svn to point to the subversion repo: +====== FAQ ======
-$ git svn init -Thead svn+ssh://$GIT_SVN_URI .+
  
-# Now you'll want to look in .git/config and make sure that  +  * I want authornames! Use the .gitauthors file in the root of the ports tree. 
-# it has a config section that looks like this: +  * Why the full history and not only since day X It would make the history incompatible with other people's repository and the space savings are simply not worth the hassle. As of Oct/2012, all revisions make up about 933MB.
-#[svn-remote "svn"] +
-#        url = svn+ssh://svn.freebsd.org/base   (or /ports, if cloning those) +
-#        fetch = head:refs/remotes/origin/trunk +
-# +
-# People w/o write access to SVN can use this instead: +
-#   $ git svn init -Thead --rewrite-root=svn+ssh://$GIT_SVN_URI svn://$GIT_SVN_URI .+
  
-# Now what we have to do is get 'master' to be tracking 'svn_head':+Everything done is so that everybody can verify the integrity of the conversion using the tools mentioned in this article. Hence the focus on repeat-ability of the process.
  
-# Now make a git branch 'trunk' for git-svn to follow.  What we want to do it set it to point to the final commit in origin/svn_head. +====== Known Problems ======
-$ git update-ref refs/remotes/origin/trunk `git show-ref origin/svn_head|cut -d" " -f1` # git-svn really needs this branch+
  
-# Sync with the FreeBSD svn repo and reconstruct the necessary metadata.   +  * SVN merges for single revisions (that span only parts of the tree then), are not really representable as merges in git and instead are called cherry-picks there. The converter tries to be smart about whole tree merges however -- this heuristic is only activated for the head/, user/, and projects/ branches. A whole-tree merge of project/foo into head/ should thus be correctly represented in git. Merges from head/ to stable/ or from contrib/ to head/ will be plain commits, i.e. "cherry-picks".
-# This should be pretty fast and output looks like a list of revisions that start above 100,000. +
-$ git svn fetch  +
  
-# Arrange to have 'master' reference 'trunk' +===== September 2019 notes/commits force push =====
-$ git checkout trunk; git branch -D master # delete master +
-$ git checkout -b master trunk # and have master hang off trunk+
  
-# Get pull requests from the repos: +Sometime around September 2019, refs/notes/commits was force-pushed, breaking fast-forward fetch.  If you had a copy of notes before this, ''%%git fetch%%'' won't automatically update notes do to this change.  To force reset your local copy to the new copy, use:
-$ git config --add remote.origin.fetch '+refs/pull/*:refs/remotes/origin/pull/*' +
-$ git fetch +
- +
-# Finally do a final update from head. +
-$ git svn rebase +
-</code> +
- +
-Now you can periodically sync to svn using ''%%git svn rebase%%'' and you can push small changes back to svn using ''%%git svn dcommit%%'', but read on. +
- +
-Things to keep in mind: +
- +
-  * Never ''%%git merge%%'' branches, unless you know what you're doing. +
-  * Always ''%%git rebase%%'' your work on top of ''%%master%%'', then ''%%git svn dcommit%%'' can push the top commits to svn. +
-  * Always double-check with ''%%git svn dcommit -n%%'' to see what would happen. +
-  * While you can use ''%%git add%%'' for new files just fine, you won't be able to push those upstream, you can however use the patch, apply it to some subversion checkout and do the commit there. This is a shortcoming of our very own Subversion hacks, but hey, it's better than nothing! +
-  * While ''%%git-svn%%'' now allows you to set ''%%svn:mergeinfo%%'' when committing, this is so fragile that the %%FreeBSD%% projects discourages its use. Please use svn(1) for merging, sorry. +
- +
-===== Merging pull requests from github using git-svn (FreeBSD committers only) =====+
  
 <code> <code>
- +$ git fetch -f <freebsd> refs/notes/commits:refs/notes/<commits_note_name>
-# +
-# Begin single port submit via pull request: +
-# +
- +
-# Get most up to date version of everything from github (all the new pull requests) +
-$ git fetch +
- +
-# Make sure you local copy is up to date +
-$ git svn rebase +
- +
-# Now get the user's change onto the git-svn branch: +
-# ...an editor will pop up right after you run this command, see the next section for what to do. +
-$ git rebase -i --onto master origin/master origin/pull/21/head +
- +
-# Inside the editor you'll want to "squash" the commits so that SVN only gets a single commit. +
-# If there is only a SINGLE "pick" line like: +
-#     "pick 251f162 Try to fix @sample usage" +
-# then just save+quit out of your editor. +
-# +
-# However if there are multiple "pick" lines you will want to flatten (squash) all of the changes into a single commit. +
-# +
-# Example, if you see this: +
-# +
-#   pick 251f162 Try to fix @sample usage. +
-#   pick 6c96c06 using VAR as both OPTION and PLIST_SUB doesn't seem to work. +
-#   pick c259e63 Use auto PLIST_SUB stuff. +
-# +
-# Change it to this: +
-# +
-#   pick 251f162 Try to fix @sample usage. +
-#   s 6c96c06 using VAR as both OPTION and PLIST_SUB doesn't seem to work. +
-#   s c259e63 Use auto PLIST_SUB stuff. +
-# +
-# Save+quit the editor, then another editor will pop up for you to combine the commit messages. +
-# Then cleanup the commit message and save+quit. +
-# +
- +
-# Now you are ready for commit... almost, you must add freebsd properties. +
-# +
-# Now add FreeBSD required properties. +
-# +
-# XXX: at this point you'll need to add svn properties to the files, I have proposed modification to the +
-# freebsd port for git that supports this propset.  It is here: https://reviews.freebsd.org/D1154 +
-# +
-# this only works if you have git port compiled with these patches: +
-# https://reviews.freebsd.org/D1154?download=true +
-# $ git svn propset REQUIRED_PROPNAME REQUIRED_PROPVAL files... +
-# +
-# Probably something like: +
-$ git svn propset svn:keywords "FreeBSD=%H" devel/py-tipper/Makefile +
-$ git svn propset fbsd:nokeywords yes devel/py-tipper/pkg-descr +
-$ git svn propset fbsd:nokeywords yes devel/py-tipper/distinfo  +
- +
-# make sure the commits look OK: +
-$ git svn dcommit -n +
- +
-# Show the actual diff. +
-$ git diff `git svn dcommit -n | grep '^diff-tree'| cut -f 2,3 -d" "` +
- +
-# actually commit it... +
-$ git svn dcommit+
 </code> </code>
  
-==== Experimental git-svn bootstrap ==== +Where ''%%freebsd%%'' is the name of your %%FreeBSD%% Git remote (if you're not sure, try ''%%origin%%'').  Here, ''%%commits_note_name%%'' is the name of your local copy of %%FreeBSD%% ''%%refs/notes/commits%%'' (if you followed the procedure in this wiki page, try ''%%commits%%'').
- +
-There is an experimental git-svn bootstrap for quickly getting a complete git-svn enabled repository of your own. +
- +
-Visit https://github.com/idaemons/freebsd and follow the instructions described in the README file. +
- +
-====== FAQ ====== +
- +
-  * I want authornames! Good for you, and this has been done but abandoned again for various reasons: There's no authoritative, complete and //stable// mapping of svn users to "Name %%<%%email>" pairs. Especially for people without access to freefall. Random contributors are more likely to have a conversion using the current parameters. +
-  * Why the full history and not only since day X It would make the history incompatible with other people's repository and the space savings are simply not worth the hassle. As of Oct/2012, all revisions make up about 933MB. +
- +
-Everything done is so that everybody can verify the integrity of the conversion using the tools mentioned in this article. Hence the focus on repeat-ability of the process.+
  
 ====== Verification ====== ====== Verification ======
Line 227: Line 131:
 ... ...
 Exported revision 243246. Exported revision 243246.
-$ git clone --config remote.origin.fetch='+refs/notes/*:refs/notes/*' git://github.com/freebsd/freebsd.git freebsd.git+$ git clone --config remote.origin.fetch='+refs/notes/*:refs/notes/*' https://github.com/freebsd/freebsd.git freebsd.git
 $ cd freebsd.git && git pull $ cd freebsd.git && git pull
 $ git log $ git log
Line 276: Line 180:
  
 See the project branch at [[http://svn.freebsd.org/base/user/uqs/git_conv/]] for extra patches, rules and the scripts used to do these conversions. See the project branch at [[http://svn.freebsd.org/base/user/uqs/git_conv/]] for extra patches, rules and the scripts used to do these conversions.
 +
 +----
 +
 +{{tag>HowTo}}
  
  • gitworkflow.1429741075.txt.gz
  • Last modified: 2015/04/22 22:17
  • by CraigRodrigues