|
|
| Line 1: |
Line 1: |
| − | The Dreamwidth code uses a Git repository and is publicly available [http://github.com/dreamwidth/ on Github].
| + | #REDIRECT [[Newbie Guide: How To in Git]] |
| − | | + | |
| − | You can orient yourself with the basics via [[Git Getting Started]] and the [[Dev_Getting_Started#Workflow|sample workflow]] in [[Dev Getting Started]]. Instructions for specific actions are below:
| + | |
| − | | + | |
| − | = Important note (or: Why am I getting 'Permission denied'?) =
| + | |
| − | | + | |
| − | Before running any of the <tt>git</tt> commands on this page, you will need to ensure you are somewhere within the <tt>$LJHOME</tt> directory tree. On Dreamhacks, if you are not within this directory tree, you may receive errors like this:
| + | |
| − | | + | |
| − | fatal: Unable to create '/dreamhack/.git/refs/heads/dj.lock': Permission denied
| + | |
| − | | + | |
| − | This occurs because the Dreamhack machine uses its own git repository for its code too, and Git is thinking that you wanted to use this repository instead of your own personal repository. To fix this, simply change to the <tt>$LJHOME</tt> directory:
| + | |
| − | | + | |
| − | cd $LJHOME
| + | |
| − | | + | |
| − | The commands should now work without issue.
| + | |
| − | | + | |
| − | = Starting a new branch =
| + | |
| − | | + | |
| − | New branches should be started from an up-to-date copy of develop: see [[Dev_Maintenance#Updating_dw-free|the Dev Maintenance article for instructions on how to do this]].
| + | |
| − | | + | |
| − | To create a new branch and switch your working copy over to it immediately, use <tt>git checkout -b ''branchname''</tt>; eg
| + | |
| − | | + | |
| − | git checkout -b bug4335-admin-tt
| + | |
| − | | + | |
| − | Choose a descriptive branch name you can keep track of--in this example, it's the bug number being worked on, plus a couple of keywords so you're not relying solely on memorizing bug numbers.
| + | |
| − | | + | |
| − | = Managing changes =
| + | |
| − | | + | |
| − | Before making changes to a branch, make sure you have that branch checked out. You can check which branch you're currently working on with:
| + | |
| − | | + | |
| − | git branch
| + | |
| − | | + | |
| − | It will list the branches and put an asterisk next to the one you currently have checked out, eg:
| + | |
| − | | + | |
| − | bug4650-update-bootstrap.pl
| + | |
| − | bug4772-stats-old-urls
| + | |
| − | bug4772-stats-old-urls-dw-style
| + | |
| − | bug5003-remove-hg-links
| + | |
| − | * develop
| + | |
| − | master
| + | |
| − | | + | |
| − | If the current branch isn't the one you want to work on, change to the right branch with the command:
| + | |
| − | | + | |
| − | git checkout BRANCHNAME
| + | |
| − | | + | |
| − | == Viewing changes ==
| + | |
| − | | + | |
| − | To get an overview of which files have changed, which files are included in your next commit, and what new files exist, use:
| + | |
| − | | + | |
| − | git status
| + | |
| − | | + | |
| − | To get a line by line description of all of the changes, use:
| + | |
| − | | + | |
| − | git diff
| + | |
| − | | + | |
| − | When you want the changes you've made to a file you have to be included in your next commit, use <code>git add</code>:
| + | |
| − | | + | |
| − | git add FILE
| + | |
| − | | + | |
| − | If you make more changes to that file, you will have to add it again to have the new changes included.
| + | |
| − | | + | |
| − | == Stashing and unstashing ==
| + | |
| − | | + | |
| − | Sometimes you may have changes you are not ready to commit yet, but need to stow away while doing tasks like merging. <code>git stash</code> can be useful for this.
| + | |
| − | | + | |
| − | To save a bunch of changes:
| + | |
| − | | + | |
| − | git stash
| + | |
| − | | + | |
| − | To put the changes back:
| + | |
| − | | + | |
| − | git stash pop
| + | |
| − | | + | |
| − | == Undoing changes ==
| + | |
| − | | + | |
| − | If you have a file with changes and want to revert it to what's currently committed to the branch of the repository you are on, use:
| + | |
| − | | + | |
| − | git checkout -- FILENAME
| + | |
| − | | + | |
| − | If you accidentally added a file to the staging area you are going to be committing, you can unadd it using:
| + | |
| − | | + | |
| − | git reset HEAD FILENAME
| + | |
| − | | + | |
| − | If you want to reset ALL files to what's currently committed to the branch of the repository you are on and discard all changes, use:
| + | |
| − | | + | |
| − | {{Warn|text=DO NOT USE IF YOU WANT TO SAVE ANYTHING!}}
| + | |
| − | | + | |
| − | git reset --hard
| + | |
| − | | + | |
| − | == Committing changes ==
| + | |
| − | | + | |
| − | Use <code>git add</code> to add the changes you want to commit. Before committing, you may want to briefly review your changes with <code>git status</code> and <code>git diff</code>.
| + | |
| − | | + | |
| − | Once you are satisfied that these changes are the ones you want to make, give the command:
| + | |
| − | | + | |
| − | git commit
| + | |
| − | | + | |
| − | This will open up the command line editor specified in your config. (You can change this with instructions in [[Git settings]].) Write up a good description of the changes included in this commit.
| + | |
| − | | + | |
| − | Git commit messages have a format that's rather peculiar to Git, and we have a further convention of ending the summary with "Fixes #XXX" - please do include the #! So, ideally your commit messages will look something like this:
| + | |
| − | | + | |
| − | '''short summary; total 50 chars or less. Fixes #XXX'''
| + | |
| − |
| + | |
| − | After a blank line, give a long-form description of the changes.
| + | |
| − | You can write a few sentences, several paragraphs, or an essay
| + | |
| − | complete with theorems, premises, and supporting references --
| + | |
| − | whatever is needed to clearly document the change.
| + | |
| − | | + | |
| − | The first line is used as a summary by tools like <code>git log --oneline</code>; if it is too long, the output of these tools will display oddly.
| + | |
| − | | + | |
| − | [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Additional suggestions on writing commit messages].
| + | |
| − | | + | |
| − | If you are making a commit that only needs a short explanation, you can use the -m option:
| + | |
| − | | + | |
| − | git commit -m "This describes the change that I just made. Fixes #963"
| + | |
| − | | + | |
| − | If you need to make further changes you can either do a second commit or amend your initial commit with:
| + | |
| − | | + | |
| − | git commit --amend
| + | |
| − | | + | |
| − | == Rebasing commits ==
| + | |
| − | | + | |
| − | {{Warn|text=This isn't a mandatory step and can cause irreversible damage. Most patches are fine as-is and there is no point in rewriting history. Also don't do this if some of your changes have been pulled by anybody.}}
| + | |
| − | | + | |
| − | While in some instances it can be very useful to make successive commits within a single branch while working on your fix, in other ones it can be neater and tidier if you [http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html <code>rebase</code>] so that your patch consists of a single commit.
| + | |
| − |
| + | |
| − | First use <code>git branch</code> to make sure you're in the correct branch. Then do:
| + | |
| − | | + | |
| − | git rebase -i HEAD~X
| + | |
| − | | + | |
| − | replacing X with the number of commits you have made as part of your patch. You will be provided with a screen that lists your last X commits by commit number (oldest first) with their brief commit messages.
| + | |
| − | | + | |
| − | Typically, you will want to change <code>pick</code> next to the first commit to <code>reword</code>, and all subsequent instances of <code>pick</code> to <code>fixup</code>. This ''squashes'' all your commits into a single commit, discarding all commit messages but that associated with the first commit, and allowing you to edit your commit message.
| + | |
| − | | + | |
| − | You now have a single commit!
| + | |
| − | | + | |
| − | As mentioned in [[Newbie_Guide:_How_To_in_Git#How_to_squash_several_commits_into_one|this article]] you can also use the rebaser to do other nifty things or do this differently.
| + | |
| − | | + | |
| − | == Updating your branch ==
| + | |
| − | | + | |
| − | {{Warn|text=This isn't a mandatory step and can cause merging conflicts you'll have to resolve manually. If your patch works against current code it's actually a good sign you don't need to do this.}}
| + | |
| − | | + | |
| − | If it's been a while since you've worked on your bug, you may want to or need to bring your branch up to date with any changes that have happened in <tt>develop</tt> since you initially forked your branch.
| + | |
| − | | + | |
| − | In this case, first, double-check that you're in the branch you want to submit:
| + | |
| − | | + | |
| − | git branch
| + | |
| − | | + | |
| − | Then fetch changes from Dreamwidth's develop branch and bring your branch up to date with them:
| + | |
| − | | + | |
| − | git fetch dreamwidth
| + | |
| − | git pull --rebase --ff-only dreamwidth develop
| + | |
| − | | + | |
| − | <tt>pull --rebase</tt> incorporates any new changes from develop into your branch, and it also reorganizes your changes so that changes in your branch appear to start from ''current'' develop, instead of where develop was when you initially started your branch. (Neat!) This can make it much easier to merge your branch into Dreamwidth's main develop branch.
| + | |
| − | | + | |
| − | == Pushing your changes to your repository on Github ==
| + | |
| − | | + | |
| − | After committing your changes, you need to push them to your repository on Github. You can do this with:
| + | |
| − | | + | |
| − | git push origin BRANCHNAME
| + | |
| − | | + | |
| − | If you've rebased after pushing multiple commits to your repository, when you try to push your unified single commit you will get the error message ''Updates were rejected because the tip of your current branch is behind its remote counterpart''. If this is the case, you'll need to set the <code>force</code> flag when pushing, and then you should be good to go:
| + | |
| − | | + | |
| − | git push --force origin BRANCHNAME
| + | |
| − | | + | |
| − | = Making a pull request =
| + | |
| − | | + | |
| − | == Submit! ==
| + | |
| − | | + | |
| − | Go to your version of the repository (dw-free or dw-nonfree) that you want to send upstream. By default they should be at:
| + | |
| − | | + | |
| − | * https://github.com/USERNAME/dw-free
| + | |
| − | * https://github.com/USERNAME/dw-nonfree
| + | |
| − | | + | |
| − | These repositories are separate, so if you have made changes to both of them, you will have to submit pull requests for both of them.
| + | |
| − | | + | |
| − | Find your branch in the drop-down menu then click on Compare and Pull Request right above it. Check your request one last time then click on Send Pull Request. Make sure you've included the sentence "Fixes issue #XXX", where #XXX is the issue number in your commit message - this makes record-keeping/issue-tracking much easier!
| + | |
| − | | + | |
| − | {{Expand|text=Describe making a pull request to another repository other than the DW one!}}
| + | |
| − | | + | |
| − | All pull requests are reviewed by a senior Dreamwidth developer before committing (or returning for further work). {{Expand|text=The turnaround does depend on the developers' schedule; what is a typical maximum time to expect?}}
| + | |
| − | | + | |
| − | == Updating a pull request ==
| + | |
| − | | + | |
| − | Following feedback you may need to edit your patch, and get the edits live on Github. In order to do this, commit your changes (section 2.4) and push the changes to your repository on Github (section 2.6). Your pull request will automatically update to reflect the changes you've made.
| + | |
| − | | + | |
| − | Comment on your pull request once you're happy that you've done all the changes the reviewer has asked for, and have pushed up your changes. This makes it more likely that someone will take a look at your changes quickly: reviewers aren't notified of new commits, but they are notified when there are new comments.
| + | |
| − | | + | |
| − | = Making a pull request with an emergency fix =
| + | |
| − | | + | |
| − | Emergency fixes for issues that pop up right after a code push go into the release branch for the code push instead of the main develop branch. That way, regular development of features can go on as usual while the push-related issues can be fixed and pushed live on the site ASAP.
| + | |
| − | | + | |
| − | == Getting the release branch ==
| + | |
| − | | + | |
| − | You need to make your changes on the latest release branch. To do that, run these commands:
| + | |
| − | | + | |
| − | # get the latest version of the code, including any new branches
| + | |
| − | $ git fetch
| + | |
| − | ....
| + | |
| − | | + | |
| − | # checkout the release branch
| + | |
| − | $ git checkout -t dreamwidth/release-1.xx
| + | |
| − | Branch release-1.xx set up to track remote branch release-1.xx from dreamwidth.
| + | |
| − | Switched to a new branch 'release-1.xx'
| + | |
| − | | + | |
| − | == Making your fixes ==
| + | |
| − | | + | |
| − | You'll want to have all your fixes be based on the release branch, and not develop, so when you make your branch to put fixes on, be sure to specify that you want it off the release branch:
| + | |
| − | | + | |
| − | $ git checkout release-1.xx -b BRANCH_NAME
| + | |
| − | | + | |
| − | == Submitting your pull request ==
| + | |
| − | | + | |
| − | Similar to above, with one additional change. At the top of the page, it will say "dreamwidth: develop" ... "your-username:BRANCH_NAME"
| + | |
| − | | + | |
| − | Select the "Edit" button and these will turn into dropdowns. Edit the second dropdown from "base: develop" and select the current release instead.
| + | |
| − | | + | |
| − | | + | |
| − | = Deleting branches =
| + | |
| − | | + | |
| − | {{Warn|text=Be careful when deleting branches -- while it's often possible to get things back, it can be tricky to do so.}}
| + | |
| − | | + | |
| − | You might create a branch by mistake, or have your changes pulled into the main develop branch on Dreamwidth. To delete the branch locally, use the command:
| + | |
| − | | + | |
| − | git branch -d BRANCHNAME
| + | |
| − | | + | |
| − | If it's a branch that hasn't been merged yet, the above command will give you an error. If you are SURE you still want to delete that branch, use:
| + | |
| − | | + | |
| − | git branch -D BRANCHNAME
| + | |
| − | | + | |
| − | If the branch is also on your Github, you can delete it like this:
| + | |
| − | | + | |
| − | git push origin --delete <branchName>
| + | |
| − | | + | |
| − | or like this:
| + | |
| − | | + | |
| − | git push origin :<branchName>
| + | |
| − | | + | |
| − | or, if it's been merged, delete it directly from Github using the nifty Delete button.
| + | |
| − | | + | |
| − | = Untangling messes =
| + | |
| − | | + | |
| − | If your account or branch is in some kind of unfortunate state that you do not know how to recover from:
| + | |
| − | | + | |
| − | * try not to panic
| + | |
| − | * try not to blame yourself -- this is a very common situation, especially while first getting used to git.
| + | |
| − | * feel free to ask for help, particularly in <dwcomm>dw_dev_training</dwcomm> or, for real-time support, in [[IRC|#dreamwidth-dev]]; it can help to come prepared with a pastebin link of what's going on in your account, and explain what you're trying to do.
| + | |
| − | | + | |
| − | [[Category: Development]]
| + | |
| − | [[Category: Git]]
| + | |
