|Some documentation on using GitHub, including links to various Stack-Overflow answers
Current network of Audacity changes at GitHub.
- Create a free account at GitHub.
- Logged in as yourself, navigate to https://github.com/audacity/audacity and in the top right button, click "Fork"
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)
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
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.
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.
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.
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.
StackOverflow [SO] links are generally excellent. Sometimes the second answer has more votes and is better than the accepted answer.
- Use of git bisect to work out which revision caused an issue
- SO: Delete a GitHub branch locally and remotely - deleting a master branch at GitHub is harder. You have to delete the GitHub repository, refork audacity and recreate the branches from your local ones.
- SO: Disable MSVC2013 Git Integration - The reason you want to do this is that the Git integration is buggy and crashes MSVC2013 Express repeatedly.
- SO: Disable push for a repo - I've (locally) disabled push for github.com/audacity/audacity so that I don't accidentally push to it. I want all my pushes to be to github.com/JamesCrook/audacity.
- SO: Renaming a branch in GitHub - this could be used, for example, if you merge something you didn't mean to into master.
- SO: How to make all remote branches available locally with Git?
- SO: How to update GitHub forked repository? - the explanation of the use of origin and upstream is good. The part about rebase is no longer true. rebase -f should be used with care. It is fine, even good on a completely private local branch. For a public branch that someone else is using, it is probably bad.
- SO: What are the differences between 'git pull' and 'git fetch'?
- SO: Reset my local repository to be just like remote repository HEAD
- SO: GitHub fork is git clone? GitHub fork seems to be git clone with a few GitHub tweaks and restrictions. I can clone audacity/audacity to two different places on my local machine, and I but not GitHub know about these. I can fork audacity/audacity once only to my GitHub user account, and GitHub knows and shows it on the audacity/audacity network, and won't let me fork it again as that user.
- GitHub Pull Requests
- Gists:How to fetch pull requests locally, without adding the remote repo. The 'fetch = +refs/pull/*/head:refs/remotes/origin/pr/*' line in .git/config
- SO: Untrack all deleted files
- lol and lola - graphical history shown in the console
- SO: Make bash history save the commands entered in previous sessions
- Problems running git on Windows
these ones are FYI links, rarely used, e.g. when converting a repository from svn to git, which takes 4 days.
- A faster git svn fetch, provided you already have the actual svn repo with all its history on your machine. Not as great as it sounds as using svnsync also takes a long long time. Linux solution. Requires an old version of Qt.
- GitHub policy on name squatting
- GitHub rights/roles management
- Configure anything
- SO: removing oops.iso (a big file we didn't mean to check in) from history
To change capitalisation of a file (on Windows)
git mv -f Build.txt build.txt
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.
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 &