diff options
Diffstat (limited to 'doc/git-howto.txt')
| -rw-r--r-- | doc/git-howto.txt | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/doc/git-howto.txt b/doc/git-howto.txt deleted file mode 100644 index 036b567084..0000000000 --- a/doc/git-howto.txt +++ /dev/null @@ -1,272 +0,0 @@ - -About Git write access: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before everything else, you should know how to use GIT properly. -Luckily Git comes with excellent documentation. - - git --help - man git - -shows you the available subcommands, - - git <command> --help - man git-<command> - -shows information about the subcommand <command>. - -The most comprehensive manual is the website Git Reference - -http://gitref.org/ - -For more information about the Git project, visit - -http://git-scm.com/ - -Consult these resources whenever you have problems, they are quite exhaustive. - -You do not need a special username or password. -All you need is to provide a ssh public key to the Git server admin. - -What follows now is a basic introduction to Git and some Libav-specific -guidelines. Read it at least once, if you are granted commit privileges to the -Libav project you are expected to be familiar with these rules. - - - -I. BASICS: -========== - -0. Get GIT: - - You can get git from http://git-scm.com/ - - -1. Cloning the source tree: - - git clone git://git.libav.org/libav.git <target> - - This will put the Libav sources into the directory <target>. - - git clone git@git.libav.org:libav.git <target> - - This will put the Libav sources into the directory <target> and let - you push back your changes to the remote repository. - - -2. Updating the source tree to the latest revision: - - git pull (--ff-only) - - pulls in the latest changes from the tracked branch. The tracked branch - can be remote. By default the master branch tracks the branch master in - the remote origin. - Caveat: Since merge commits are forbidden at least for the initial - months of git --ff-only or --rebase (see below) are recommended. - --ff-only will fail and not create merge commits if your branch - has diverged (has a different history) from the tracked branch. - -2.a Rebasing your local branches: - - git pull --rebase - - fetches the changes from the main repository and replays your local commits - over it. This is required to keep all your local changes at the top of - Libav's master tree. The master tree will reject pushes with merge commits. - - -3. Adding/removing files/directories: - - git add [-A] <filename/dirname> - git rm [-r] <filename/dirname> - - GIT needs to get notified of all changes you make to your working - directory that makes files appear or disappear. - Line moves across files are automatically tracked. - - -4. Showing modifications: - - git diff <filename(s)> - - will show all local modifications in your working directory as unified diff. - - -5. Inspecting the changelog: - - git log <filename(s)> - - You may also use the graphical tools like gitview or gitk or the web - interface available at http://git.libav.org/ - -6. Checking source tree status: - - git status - - detects all the changes you made and lists what actions will be taken in case - of a commit (additions, modifications, deletions, etc.). - - -7. Committing: - - git diff --check - - to double check your changes before committing them to avoid trouble later - on. All experienced developers do this on each and every commit, no matter - how small. - Every one of them has been saved from looking like a fool by this many times. - It's very easy for stray debug output or cosmetic modifications to slip in, - please avoid problems through this extra level of scrutiny. - - For cosmetics-only commits you should get (almost) empty output from - - git diff -w -b <filename(s)> - - Also check the output of - - git status - - to make sure you don't have untracked files or deletions. - - git add [-i|-p|-A] <filenames/dirnames> - - Make sure you have told git your name and email address, e.g. by running - git config --global user.name "My Name" - git config --global user.email my@email.invalid - (--global to set the global configuration for all your git checkouts). - - Git will select the changes to the files for commit. Optionally you can use - the interactive or the patch mode to select hunk by hunk what should be - added to the commit. - - git commit - - Git will commit the selected changes to your current local branch. - - You will be prompted for a log message in an editor, which is either - set in your personal configuration file through - - git config core.editor - - or set by one of the following environment variables: - GIT_EDITOR, VISUAL or EDITOR. - - Log messages should be concise but descriptive. Explain why you made a change, - what you did will be obvious from the changes themselves most of the time. - Saying just "bug fix" or "10l" is bad. Remember that people of varying skill - levels look at and educate themselves while reading through your code. Don't - include filenames in log messages, Git provides that information. - - Possibly make the commit message have a terse, descriptive first line, an - empty line and then a full description. The first line will be used to name - the patch by git format-patch. - - -8. Renaming/moving/copying files or contents of files: - - Git automatically tracks such changes, making those normal commits. - - mv/cp path/file otherpath/otherfile - - git add [-A] . - - git commit - - Do not move, rename or copy files of which you are not the maintainer without - discussing it on the mailing list first! - -9. Reverting broken commits - - git revert <commit> - - git revert will generate a revert commit. This will not make the faulty - commit disappear from the history. - - git reset <commit> - - git reset will uncommit the changes till <commit> rewriting the current - branch history. - - git commit --amend - - allows to amend the last commit details quickly. - - git rebase -i origin/master - - will replay local commits over the main repository allowing to edit, - merge or remove some of them in the process. - - Note that the reset, commit --amend and rebase rewrite history, so you - should use them ONLY on your local or topic branches. - - The main repository will reject those changes. - -10. Preparing a patchset. - - git format-patch <commit> [-o directory] - - will generate a set of patches for each commit between <commit> and - current HEAD. E.g. - - git format-patch origin/master - - will generate patches for all commits on current branch which are not - present in upstream. - A useful shortcut is also - - git format-patch -n - - which will generate patches from last n commits. - By default the patches are created in the current directory. - -11. Sending patches for review - - git send-email <commit list|directory> - - will send the patches created by git format-patch or directly generates - them. All the email fields can be configured in the global/local - configuration or overridden by command line. - Note that this tool must often be installed separately (e.g. git-email - package on Debian-based distros). - -12. Pushing changes to remote trees - - git push - - Will push the changes to the default remote (origin). - Git will prevent you from pushing changes if the local and remote trees are - out of sync. Refer to 2 and 2.a to sync the local tree. - - git remote add <name> <url> - - Will add additional remote with a name reference, it is useful if you want - to push your local branch for review on a remote host. - - git push <remote> <refspec> - - Will push the changes to the remote repository. Omitting refspec makes git - push update all the remote branches matching the local ones. - -13. Finding a specific svn revision - - Since version 1.7.1 git supports ':/foo' syntax for specifying commits - based on a regular expression. see man gitrevisions - - git show :/'as revision 23456' - - will show the svn changeset r23456. With older git versions searching in - the git log output is the easiest option (especially if a pager with - search capabilities is used). - This commit can be checked out with - - git checkout -b svn_23456 :/'as revision 23456' - - or for git < 1.7.1 with - - git checkout -b svn_23456 $SHA1 - - where $SHA1 is the commit SHA1 from the 'git log' output. - - -Contact the project admins <git at libav dot org> if you have technical -problems with the GIT server. |