Differences

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

--- dev:using_git [2021/04/01 03:31]
tedfelix
+++ dev:using_git [2021/04/23 23:20]
tedfelix [Resyncing master]
@@ Line 1: / Line 1: @@
 ====== Using git ======
-git is a general purpose version control system that supports numerous workflows.  This document discusses three key ways to use git.
+git is a general purpose version control system that supports numerous workflows.  This document discusses two key ways to use git.
   * Testing Workflow - For testers who won't be making changes.
-  * Developer Workflow (Simiplified) - If you will be making changes.
+  * Developer Workflow (Fork) - If you will be making changes.
-  * Branching Workflow - More advanced git usage for developers.
-If you want to go even deeper into git, the git book will take you there:
-  https://git-scm.com/book/en/v2
 ===== Testing Workflow =====
@@ Line 19: / Line 14: @@
   git clone git://git.code.sf.net/p/rosegarden/git rosegarden-git
-That will create a rosegarden-git directory where you can build and test as usual.
+That will create a rosegarden-git directory where you can build and test as usual.  See the README in that directory for build instructions.
+  cd rosegarden-git
+  less README
-If you want to get the latest, you can fetch and rebase.  This is similar to "svn update".
+If you want to get the latest, you can pull.  This is similar to "svn update".
-  git fetch --tags
+  git pull --tags
-  git rebase
 To examine your local copy of the history, use git log.
@@ Line 36: / Line 33: @@
 And that should be everything you need for testing and using the latest.  Questions are always welcome on the users mailing list.
-===== Developer Workflow (Simplified) =====
+===== Developer Workflow (Fork) =====
-The simplest way to work with git as a developer is to avoid branches and commit changes directly to your master branch.
+//A note on learning git...  With git it helps to understand a little about the internals.  E.g. the fact that it is just a branching linked list of commits.  Then it starts to make sense.  Also playing with a small experimental repo can build confidence quickly.//
-To get started, you'll need to fork the repo you want to work on.  This makes a public copy that can only be modified by you.  In sourceforge, click the "fork" link in the left column of the code viewer.
+Before you use git for the first time, you must tell it your name and email address.
-  https://sourceforge.net/p/rosegarden/git/ci/master/tree/
+  git config --global user.name "Joe Smith"
+  git config --global user.email j.smith@gmail.com
+This will appear in all of your commits, so make sure it's correct.
+Next, you'll need to fork the repo you want to work on.  This makes a public copy that can only be modified by you.  In sourceforge, click the "fork" link in the left column of the code viewer.
+https://sourceforge.net/p/rosegarden/git/ci/master/tree/
 It will allow you to set the home project (use the default which is your sourceforge userid), the label (this is the unique name that appears in your profile), and the mount point (the name in the URL it creates).  Just go with defaults for your first fork.  Usually, defaults will be fine.
@@ Line 50: / Line 54: @@
 Wait a few moments and do a refresh and the repo should appear.  Now you can clone it using "ssh" protocol so you can write (push) to it.  Use the command that appears in the "Read/Write SSH access" box to do your clone.  It will look something like this:
-  git clone ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden tedfelix-rosegarden
+  git clone ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden rosegarden-git
+That will create a local "rosegarden-git" directory that you can build and test from.  And since this will be connected to your remote fork, you can make changes locally and push them to the remote server as well.
+From here on out we'll assume you are in your local rosegarden-git directory.
+  cd rosegarden-git
+As a final step, you'll need to configure a remote called "upstream" so that you can stay in sync with the official Rosegarden repo.
+  git remote add upstream git://git.code.sf.net/p/rosegarden/git
+After that you should have two remotes configured appropriately:
+  $ git remote -v
+  origin	ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden (fetch)
+  origin	ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden (push)
+  upstream	git://git.code.sf.net/p/rosegarden/git (fetch)
+  upstream	git://git.code.sf.net/p/rosegarden/git (push)
+Now you are ready to make changes.
-That will create a "tedfelix-rosegarden" directory that we can build and test from.  And since this will be connected to your fork, you can make changes and push them as well.
+==== Making Changes ====
-As with svn, you can use "git status" to see what you have changed.
+Before making any changes, make sure you are on the right branch with ''git status''.
 <file>
@@ Line 60: / Line 84: @@
 On branch master
 Your branch is up to date with 'origin/master'.
+</file>
+Currently we are on the ''master'' branch.  You should never commit changes to ''master''.  But at some point it will happen and fortunately it's relatively easy to fix.  (See "Committing to the Wrong Branch" below.)  For now let's assume we are doing things the Right Way and we are going to work in a new branch.
+Let's say we want to do some work on bug #123.  Before we begin we create a local ''bug123'' branch to work in and base it on ''master'':
+  $ git checkout -b bug123 master
+  Switched to a new branch 'bug123'
+This creates the new local branch and checks it out.  Use git status to make sure you are where you think you are:
+  $ git status
+  On branch bug123
+  nothing to commit, working tree clean
+Now you can make changes and commit them to your local bug123 branch.  As with svn, you can use "git status" to see what you have changed:
+<file>
+$ git status
+On branch bug123
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
@@ Line 96: / Line 139: @@
 </file>
-When you are ready to commit, use git add/rm and git commit.
+When you are ready to commit to your local git repo, use git add/rm and git commit.
 <file>
 $ git add .
 $ git status
-On branch master
+On branch bug123
-Your branch is up to date with 'origin/master'.
 Changes to be committed:
   (use "git restore --staged <file>..." to unstage)
@@ Line 109: / Line 150: @@
 $ git commit
-[master b142e48bd] Update README
+[bug123 7e717ac63] Update README
 file changed, 1 insertion(+), 1 deletion(-)
 </file>
+The git book covers all of this in far more detail:
 https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository
-To stay up to date, first make sure your working copy is clean.  If it isn't, either commit your changes or stash them.
+==== Merge Request ====
-  git status
+Once your changes are ready to be incorporated into the project, you'll want to push them from your local repo (fork) to your remote fork on sourceforge (origin).  Make sure you are on the correct branch.  In this case, bug123:
-Then you can fetch the latest changes and rebase your changes on them.
+  git checkout bug123
-  git fetch --tags
+The first time you push a local branch to your remote fork, you will need to set the local branch's "upstream" to ''origin'' (your remote fork) and specify the name for the new remote branch:
-  git rebase
-If you stashed changes, you can pop the stash now to get them back.
+  git push -u origin bug123
-  git stash pop
+Git will confirm that the push was successful and that the upstream was set:
-Once your changes are ready to be incorporated into the project, push them to your remote fork on sourceforge (origin).
+<file>
+To ssh://git.code.sf.net/p/rosegarden/git
+ * [new branch]          bug123 -> bug123
+Branch 'bug123' set up to track remote branch 'bug123' from 'origin'.
+</file>
+Git remembers the upstream and will use it the next time you push.  There is no need to specify ''-u origin bug123'' again:
   git push
-And then send a merge request to the owner of the original repo that you forked.  On the sourceforge website, click on the "Request Merge" link in the left column in sourceforge's code viewer.  Then fill in the summary and an optional description.  Source and target branch will be "master".
+Now you can send a merge request to the owner of the original repo that you forked.  On the sourceforge website, bring up your fork and click on the "Request Merge" link in the left column in sourceforge's code viewer.  Then fill in the summary and an optional description.  Source Branch for this example would be "bug123".  Target Branch would probably be "master".
 The owner of the original repo will then get the merge request and decide what to do with it.
-===== Branching Workflow =====
+//Note that with git the term "upstream" is used for two different things.  Most commonly it's used to refer to the remote branch that a local branch will push to.  It's also used to refer to the remote repo that was the source of your fork.//
-Creating a new branch is as simple as a checkout with the -b option.  In this case we create a new branch based on master:
+==== Branching ====
-  $ git checkout -b newbranch master
+Branching is so easy with git that it's not unusual to end up doing work on the wrong branch.  Use git status frequently to confirm which branch you are on.  Then switch to the right one before continuing.
-  Switched to a new branch 'newbranch'
-You can commit to this new branch just like you would with any other branch like master.  Before you start working, though, make sure you are in the right branch with git status.
-  $ git status
-  On branch newbranch
-  nothing to commit, working tree clean
-Switching branches is also a checkout.
+Switching local branches is simply a checkout.
   $ git checkout master
   Switched to branch 'master'
   Your branch is up to date with 'origin/master'.
-  $ git checkout newbranch
+  $ git checkout bug123
-  Switched to branch 'newbranch'
+  Switched to branch 'bug123'
+  Your branch is up to date with 'origin/bug123'.
+Check which local branch you are on with git status.
+<file>
+$ git status
+On branch bug123
+Your branch is up to date with 'origin/bug123'.
+nothing to commit, working tree clean
+</file>
 You can list your local branches.
@@ Line 161: / Line 213: @@
 <file>
 $ git branch -v
-  master    b142e48bd Update README
+* bug123    7e717ac63 Update README
-* newbranch b142e48bd Update README
+  master    f04c831e0 cmake: Pre-compiled header comments
 </file>
@@ Line 170: / Line 222: @@
 $ git remote show origin
 * remote origin
-  Fetch URL: ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden
+  Fetch URL: ssh://tedfelix@git.code.sf.net/p/rosegarden/git
-  Push  URL: ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden
+  Push  URL: ssh://tedfelix@git.code.sf.net/p/rosegarden/git
   HEAD branch: master
-  Remote branch:
+  Remote branches:
+    bug123 tracked
     master tracked
-  Local branch configured for 'git pull':
+  Local branches configured for 'git pull':
+    bug123 merges with remote bug123
     master merges with remote master
-  Local ref configured for 'git push':
+  Local refs configured for 'git push':
+    bug123 pushes to bug123 (up to date)
     master pushes to master (up to date)
 </file>
-To push a new branch to your remote fork on sourceforge (origin) be sure to specify the "upstream" with the "-u" option:
+==== Resyncing master ====
+While working with branches, don't forget to periodically fetch the latest changes to master from the upstream repo and push to resync your fork's master.  First switch to master and make sure the working directory is clean and up to date:
 <file>
-$ git checkout newbranch
+$ git checkout master
-Switched to branch 'newbranch'
+Already on 'master'
-$ git push -u origin newbranch
+Your branch is up to date with 'origin/master'.
-Total 0 (delta 0), reused 0 (delta 0)
-remote: <Repository /git/u/tedfelix/rosegarden.git> refresh queued.
-To ssh://git.code.sf.net/u/tedfelix/rosegarden
- * [new branch]          newbranch -> newbranch
-Branch 'newbranch' set up to track remote branch 'newbranch' from 'origin'.
-</file>
-After the upstream is set, you can simply say "git push" and git will remember.
+$ git status
+On branch master
+Your branch is up to date with 'origin/master'.
-  git push
+nothing to commit, working tree clean
+</file>
-While working with branches, don't forget to periodically fetch the latest changes to master.
+If it isn't clean and up to date, you'll want to fix that before continuing.  Otherwise a ''git pull'' will make a mess of things.  Assuming master is clean and up to date you can resync your master and your fork's master with a pull from upstream and a push to origin:
-  git checkout master
+  git pull --tags upstream master
-  git fetch --tags
+  git push --tags origin master
-  git rebase
+==== Deleting a Remote Branch ====
 To delete a branch from your remote fork on sourceforge (origin):
 <file>
-$ git push origin --delete newbranch
+$ git push origin --delete bug123
-remote: <Repository /git/u/tedfelix/rosegarden.git> refresh queued.
+remote: <Repository /git/p/rosegarden/git.git> refresh queued.
-To ssh://git.code.sf.net/u/tedfelix/rosegarden
+To ssh://git.code.sf.net/p/rosegarden/git
- - [deleted]             newbranch
+ - [deleted]             bug123
 </file>
-To delete a local branch:
+==== Deleting a Local Branch ====
-  $ git branch -d newbranch
+To delete a local branch, first make sure you don't have it checked out.  Switching to master is safe:
-  Deleted branch newbranch (was b142e48bd).
-Depending on whether it thinks commits may be lost, git might require you to specify "-D" to force the delete.
+  git checkout master
+Then use ''git branch -d'':
+  $ git branch -d bug123
+  Deleted branch bug123 (was 7e717ac63).
+Depending on whether it thinks commits may be lost, git might require you to specify ''-D'' to force the delete.  Make sure nothing will be lost before using ''-D''.
+==== Creating a Safety Branch ====
 And finally, if you're about to go through some scary git commands on a branch, you can always drop a safety branch that you can get back to at any time.
   git branch my-safety-branch1
-  ... (lots of scary git commands like git reset and git pull)
+  ... (lots of scary git commands like ''git reset'' and ''git branch -D'')
   git checkout my-safety-branch1
+==== Committing to the Wrong Branch ====
+It happens to all of us at some point.  This is where you can learn more about the internals of git.  Git implements its change history as a branching linked list pointing into the past.  As such, we can manipulate it in almost any way we want.
+Let's say we accidentally committed something to master that should have been committed into a new branch.
+<file>
+$ git commit -am "Update README"
+[master 556976f7d] Update README
+file changed, 1 insertion(+), 1 deletion(-)
+</file>
+Oops.  Ok, not a problem.  Let's drop the branch we wanted to create here:
+  git branch bug222
+Listing the branches we see that master and bug222 are in the same place.
+<file>
+$ git branch -v
+  bug222    556976f7d Update README
+* master    556976f7d [ahead 1] Update README
+</file>
+Also note that master is ahead by one commit that shouldn't be there.  So we need to move our local master back one commit.  There are a couple of ways to do that.  But the one that makes the most sense is to put master back where it belongs at origin/master:
+  $ git reset --hard origin/master
+  HEAD is now at f04c831e0 cmake: Pre-compiled header comments
+Now check the branches:
+<file>
+$ git branch -v
+  bug222    556976f7d Update README
+* master    f04c831e0 cmake: Pre-compiled header comments
+</file>
+That looks better.  Now we can switch to the bug222 branch where we should have been:
+  $ git checkout bug222
+  Switched to branch 'bug222'
+For handling more complex situations, look into the [[https://git-scm.com/docs/git-cherry-pick|git cherry-pick command]].
+==== Resources ====
+github has some good documentation on forking:
+https://docs.github.com/en/github/getting-started-with-github/fork-a-repo
+If you want to go even deeper into git, the git book will take you there:
+[[https://git-scm.com/book/en/v2]]
+Definitely read it after you are done with this.
+The [[https://www.oreilly.com/library/view/version-control-with/9781449345037/|O'Reilly Git Book]] is pretty good as well.