Using git

git is a general purpose version control system that supports numerous workflows. This document discusses three key ways to use git.

• Testing Workflow - For testers who won't be making changes.
• Developer Workflow (Simiplified) - 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

If you don't plan on submitting code changes, you can track development using just a few git commands.

First, you'll want to make a clone of the git repo on your local machine. This is similar to “svn checkout”.

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.

If you want to get the latest, you can fetch and rebase. This is similar to “svn update”.

git fetch --tags
git rebase

To examine your local copy of the history, use git log.

git log

Or even nicer is the gitk GUI.

gitk &

And that should be everything you need for testing and using the latest. Questions are always welcome on the users mailing list.

The simplest way to work with git as a developer is to avoid branches and commit changes directly to your master branch.

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.

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.

The fork will take a while. It is making a copy of the entire 150+MB rosegarden repo for your personal use on the sourceforge servers. Then it is analyzing that copy which takes a minute or so.

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

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.

As with svn, you can use “git status” to see what you have changed.

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   README

no changes added to commit (use "git add" and/or "git commit -a")

git diff provides all the details.

$ git diff
diff --git a/README b/README
index b17b6c4a5..f93535a00 100644
--- a/README
+++ b/README
@@ -139,7 +139,7 @@ data/appdata.  It is named rosegarden.appdata-old.xml.
 Authors and copyright
 ---------------------
 
-Rosegarden is Copyright 2000-2020 The Rosegarden Development Team
+Rosegarden is Copyright 2000-2021 The Rosegarden Development Team
 
 See http://rosegardenmusic.com/resources/authors/ for a complete list of
 developers past and present, and to learn something about the history of our

Or get a summary with “–stat”.

$ git diff --stat
 README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

When you are ready to commit, use git add/rm and git commit.

$ git add .
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   README

$ git commit
[master b142e48bd] Update README
 1 file changed, 1 insertion(+), 1 deletion(-)

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.

git status  

Then you can fetch the latest changes and rebase your changes on them.

git fetch --tags
git rebase

If you stashed changes, you can pop the stash now to get them back.

git stash pop

Once your changes are ready to be incorporated into the project, push them to your remote fork on sourceforge (origin).

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”.

The owner of the original repo will then get the merge request and decide what to do with it.

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:

$ git checkout -b newbranch master
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.

$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
$ git checkout newbranch
Switched to branch 'newbranch'

You can list your local branches.

$ git branch -v
  master    b142e48bd Update README
* newbranch b142e48bd Update README

And examine your remote branches.

$ git remote show origin
* remote origin
  Fetch URL: ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden
  Push  URL: ssh://tedfelix@git.code.sf.net/u/tedfelix/rosegarden
  HEAD branch: master
  Remote branch:
    master tracked
  Local branch configured for 'git pull':
    master merges with remote master
  Local ref configured for 'git push':
    master pushes to master (up to date)

To push a new branch to your remote fork on sourceforge (origin) be sure to specify the “upstream” with the “-u” option:

$ git checkout newbranch
Switched to branch 'newbranch'
$ git push -u origin newbranch
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'.

After the upstream is set, you can simply say “git push” and git will remember.

git push

While working with branches, don't forget to periodically fetch the latest changes to master.

git checkout master
git fetch --tags
git rebase

To delete a branch from your remote fork on sourceforge (origin):

$ git push origin --delete newbranch
remote: <Repository /git/u/tedfelix/rosegarden.git> refresh queued.
To ssh://git.code.sf.net/u/tedfelix/rosegarden
 - [deleted]             newbranch

To delete a local branch:

$ git branch -d newbranch
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.

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)
git checkout my-safety-branch1