GitHub

From Audacity Wiki
Jump to: navigation, search

This is a work in progress. May be inaccurate in places!

Current network of Audacity changes at GitHub.


Contents

Getting Started

GitHub

Congratulations! You now have a remote copy of the repo.

If you are completely new to Git, you may want to also fork https://github.com/audacity/sandbox, and use it not for Audacity but for a few example text files. This way you can get the hang of pull and push and local and remote repos without worrying about 'messing up' the audacity repo.

Clone repo locally

It is probably best to use Git Bash (command line for Git) rather than one of the fancy GUIs. There is more help on the internet about the Git command line commands. Using the command line also builds knowledge about what the GUI is doing 'under the hood'. If you're on Windows and download http://sourceforge.net/projects/gitextensions/ it comes with Git Bash. It also sets up git nicely.

On Linux, git-sh provides an interactive bash session modified for git-heavy workflows. Typical usage is to change into the directory of a git work tree or repository and then run the git-sh command to start the interactive shell session.

You need to clone a GitHub repo on your own machine. When you do this Git will create a folder called .git at the top of the directory you use for a repo. These folders contain a packed and indexed complete collection of all version history. In the directory you'll have the current version of Audacity HEAD. You do many small interactions with this repo, and eventually send your changes back up to GitHub. To clone:

  • Navigate to the directory you want to use.
  • Type the following (adding ".git" without quotes to the end of the URL works too)
git clone https://github.com/YOUR-USERNAME/audacity

You'll now have a copy of everything locally. You could in fact type "git clone https://github.com/audacity/audacity" and get the same result. However we're setting things up so you can do exactly as you like with your own repository on GitHub.

  • From here on, you can change to the "audacity" directory git created then type
git pull

to keep the local files up to date with the files in the GitHub repo. "Git pull" actually does it in two steps. First it does a "Git fetch" which brings the GitHub files into your repo. Then it does a "Git merge" to merge them with the current version of files you have.

For SVN users

Now look at the first picture on this page http://blog.osteele.com/posts/2008/05/my-git-workflow/. You might even read most of what he writes, as it shows exactly how to 'use Git as SVN'. The picture shows the local repo (on your machine) and the remote one (at GitHub). It also shows the index and the text explains why you can ignore it (mostly) when getting started with Git.

Commit results back to GitHub

Committing back to GitHub now has two steps.

git commit -a -m "Fixed Bug 1234"

just updates your local repo.

git push

actually updates the repo on GitHub.

Current Linux Build Status

Check Travis Linux Build Status. Travis pulls audacity/audacity:master from GitHub and then builds.

Collaborating

So you are interested in what else is going on on Audacity at GitHub? Go visit https://github.com/audacity/audacity/network . You'll see some branches by different people being worked on.

git remote add james https://github.com/JamesCrook/audacity

Now you have an alias for james' repo.

git fetch --all

Now your local repo is up to date. You can see James' branches in your git gui, not just on GitHub.

git checkout james/translations

You now have checked out a local copy of james' translations branch, just to look at (detached HEAD - it just means it hasn't got a local name).

git branch --track trans james/translations

Now you've named a local branch, trans, that will track james/translations. Every time you do a "git fetch --all" it will be updated.

git checkout trans

Look and work on your local copy of james/translations. Now you are not in a detached HEAD state. Your work at trans will be saved if you switch to another branch.

More Features

Git is superb for branches and in time (I am told) you will find yourself making many temporary branches for different experiments. You don't have to though.


Links

StackOverflow [SO] links are generally excellent. Sometimes the second answer has more votes and is better than the accepted answer.

Extra Links

these ones are FYI links, rarely used, e.g. when converting a repository from svn to git, which takes 4 days.


Revision Surgery

When 'sorting out mess' the cherry pick command, which stages a chosen commit on to the current branch is useful. Remember you still have to commit the commit, before you cherry pick another commit. The logic of this is that you can edit the staged commit, including what files are involved, before actually committing. The network diagram in the GitExtensions editor needs to be read carefully. It is easy to think a commit is in a branch that isn't. It is only in the branch if there is a blob on that branches track display. The network diagram at GitHub will need to be refreshed twice to come up to date.

Examples

Changing the colors in git bash. The red (for remote repos) is hard to see.

git config --global color.branch.remote "yellow"

Similarly the prompt's green for [email protected] and brown for current directory is hard to see. See SO: Setting colors for prompt in Git Bash on Windows using an extra "PS1" line. On Windows this line can be added to the file "C:\Program Files\Git\etc\profile" (or "C:\Program Files (x86)\Git\etc\profile" on 64-bit systems) or to %USERPROFILE%\.bash_profile. Use whichever file works.

When you have a complex set up, invoke the gitk GUI to explore:

gitk --all &
Personal tools

Donate securely by PayPal, using your credit card or PayPal account!