This document provides details on ACME development conventions and practices.
...
important -- Items colored in red mean they are important, and should not be ignored.
one time -- Items colored in green are commands to be issued once per machine.
repo once -- Items colored in orange are commands to be issued once per local repository.
...
Any of these options can be combined to give more flexibility to exploring the history of a git repository and make the history more useful.
Incorporating another branch on to your branch.
When developing a new feature, another developer might have created a feature you require for your work, or another developer might have made large changes to the interfaces you make use of. This section will describe how to incorporate those changes into your branch.
NOTE:
This action can have negative consequences and cause issues in the future, so it is important to know what you’re doing prior to doing any of these.
Cherry-pick method
The first option for incorporating changes from another development line into your development history is via a cherry-pick. A cherry-pick will copy individual commits (or a range of commits) from one point in history onto the HEAD of your current development line. It should be used when the number of commits your future development efforts depend on are small (order 1-10). It can be used as follows:
git cherry-pick <commit-ish>
This method is the easiest to use and one of the least likely to create issues in future development, and allows the most flexible review modifications. One downside to this method, however, is that the commits that are cherry-picked will now occur twice in the history.
Merge Method
The second option for incorporating changes into your development history is via a merge. A merge will attempt to merge an arbitrary number of other commits (or branches) into your current branch. It can be used as follows:
git merge [commit-ish1] [commit-is2] …
In this case, you can list how ever many commits you want on this line, and git will attempt to merge them all into the commit you are currently working on (into your working directory).
The merge will allow you to enter a commit message. The commit message should be very descriptive. It should explain what you’re merging, and why you’re merging it.
NOTE:
A merge creates a fixed point in history. The merge commit fixes all history before it, which limits possibilities for cleaning up history during a code review. A merge should be avoided if at all possible, but in some cases it is necessary. If it is necessary, try to clean up all history prior to the merge before beginning the merge.
Rebase Method
The third and final option for incorporating changes into your development history is via a rebase. A rebase allows you to modify commits. This includes operation such as squashing, re-ordering, deleting, etc. When you create a branch, the base of the branch is the commit you branched off of. A rebase allows you to modify what the base of your branch is. The following diagram can be used to visualize a rebase:
...
When performing a rebase, you specify the new base for your work. Rebase will then replay your work onto the new base. For example:
git rebase -i new-base
Will replay the history from the current branch on top of the new-base. The -i flag in this case allows interactive modification of the commits to replay. It should be used to verify what is going to happen after the rebase.
NOTE:
Commits that occur prior to a merge cannot be modified, or rebased. In general, if you previously merged within your branch (i.e. to incorporate an “external feature”) or if your branch was previously merged into another branch, you should not rebase anymore, because it will cause conflicts during future work.
Finishing Up
Committing changes
While working on a feature or a bug fix, you will be editing source code files. After editing a file, you might want to commit those changes to your local repository in order to checkpoint your work, or track the change you made. By default, git doesn’t track any files in the repository unless they are explicitly added to the repository. In order to add a file to the repository, you can use the following command:
git add path/to/file/in/repo
In addition to causing git to track the file, this will also stage all changes in the file. The next commit that is created will contain all changes in the stage by default. In order to commit only the changes in the staging area, the following command can be used:
git commit
NOTE: The git add command will only stage the changes in the file at the time of the git add. If the file is subsequently modified after a git add, and then a git commit is issued, the commit will not contain changes between the git add and the git commit.
This will open up an editor where a commit message can be written. The first line is the subject line and should be relatively short and concise. The second line should be blank, and every line below that can be the “body” of the commit message with as much information as needed.
An alternative way of committing all changes to any files that are currently tracked by the repository is:
git commit -a
...
Committing new files and changes as you go
While working on a feature or a bug fix, you will be editing source code files. After editing a file, you might want to commit those changes to your local repository in order to checkpoint your work, or track the change you made. By default, git doesn’t track any files in the repository unless they are explicitly added to the repository. In order to add a file to the repository, you can use the following command:
git add path/to/file/in/repo
In addition to causing git to track the file, this will also stage all changes in the file. The next commit that is created will contain all changes in the stage by default. In order to commit only the changes in the staging area, the following command can be used:
git commit
NOTE: The git add command will only stage the changes in the file at the time of the git add. If the file is subsequently modified after a git add, and then a git commit is issued, the commit will not contain changes between the git add and the git commit.
This will open up an editor where a commit message can be written. The first line is the subject line and should be relatively short and concise. The second line should be blank, and every line below that can be the “body” of the commit message with as much information as needed.
An alternative way of committing all changes to any files that are currently tracked by the repository is:
git commit -a
This will again open an editor for a commit message to be entered.
Incorporating another branch on to your branch.
When developing a new feature, another developer might have created a feature you require for your work, or another developer might have made large changes to the interfaces you make use of. This section will describe how to incorporate those changes into your branch.
NOTE:
This action can have negative consequences and cause issues in the future, so it is important to know what you’re doing prior to doing any of these.
Cherry-pick method
The first option for incorporating changes from another development line into your development history is via a cherry-pick. A cherry-pick will copy individual commits (or a range of commits) from one point in history onto the HEAD of your current development line. It should be used when the number of commits your future development efforts depend on are small (order 1-10). It can be used as follows:
git cherry-pick <commit-ish>
This method is the easiest to use and one of the least likely to create issues in future development, and allows the most flexible review modifications. One downside to this method, however, is that the commits that are cherry-picked will now occur twice in the history.
Merge Method
The second option for incorporating changes into your development history is via a merge. A merge will attempt to merge an arbitrary number of other commits (or branches) into your current branch. It can be used as follows:
git merge [commit-ish1] [commit-is2] …
In this case, you can list how ever many commits you want on this line, and git will attempt to merge them all into the commit you are currently working on (into your working directory).
The merge will allow you to enter a commit message. The commit message should be very descriptive. It should explain what you’re merging, and why you’re merging it.
NOTE:
A merge creates a fixed point in history. The merge commit fixes all history before it, which limits possibilities for cleaning up history during a code review. A merge should be avoided if at all possible, but in some cases it is necessary. If it is necessary, try to clean up all history prior to the merge before beginning the merge.
Rebase Method
The third and final option for incorporating changes into your development history is via a rebase. A rebase allows you to modify commits. This includes operation such as squashing, re-ordering, deleting, etc. When you create a branch, the base of the branch is the commit you branched off of. A rebase allows you to modify what the base of your branch is. The following diagram can be used to visualize a rebase:
When performing a rebase, you specify the new base for your work. Rebase will then replay your work onto the new base. For example:
git rebase -i new-base
Will replay the history from the current branch on top of the new-base. The -i flag in this case allows interactive modification of the commits to replay. It should be used to verify what is going to happen after the rebase.
NOTE:
Commits that occur prior to a merge cannot be modified, or rebased. In general, if you previously merged within your branch (i.e. to incorporate an “external feature”) or if your branch was previously merged into another branch, you should not rebase anymore, because it will cause conflicts during future work.
Finishing Up
Submitting a pull request
Once you think development is finished on your project, you should push the project to the shared repository (a remote), and submit a pull request for the integration of your project into master. A pull request initiates a request to merge your branch into another branchmaster. It is publicly documented in github issues in combination with the subsequent code review and discussion, and the outcome of the pull request
Once you have committed all your changes and pushed the branch is pushed to the shared repository, you can navigate to the shared repository on github. On the shared repository’s webpage, there is a “Compare and pull request” button that can be used to initiate a pull request. github.
Go to https://github.com/ACME-Climate/ACME/pulls and click "New Pull Request".
You should verify the head and base of your pull request are correct. The pull request should also be provided with a very descriptive message and title. The reviewer will review the description as part of the pull request, because the description will be the commit message used when the merge is finished.NOTE: The last commit on your branch should not be a merge commit merging master into your branch. You should almost never merge from master. The reviewer might run into unexpected merge conflicts when merging your branch into master. If that happens, the reviewer will instruct you on how to help resolve these conflicts.. The reviewer will review the description as part of the pull request, because the description will be the commit message used when the merge is finished.
After submitting the pull request, navigate to its page in github and give it a Label using the pull down menu there. Label it with the component for which the feature was developed. Add the "bug fix" label if this is a bug fix.
Using the "Assignee" menu, add the name of the designated Integrator for your component. See Integrator Guide for a list. This will start the code review and the process of moving this feature to master.
This document can be used to help with pull request related issues.
...
Below is a summary of the above sections. It will provide an ordered list of commands for a typical workflow. This will not describe why you would use these commands, or even what they do, simply a typical order for a standard project. Some items will be left out, like incorporating changes from an external project that your project is dependent on.
git clone git@github.com:ACME-Climate/ACME.git
(only need to do this once per development platform (your laptop, Mira,Titan, etc.)cd ACME
git checkout -b github-username/component/feature acme-vXX
Repeat the following until development is complete:
vim file # make changes to files, or add new files
git add new-files
git commit -a # Edit commit message, based on template
Optional: git rebase -i <commit>
Optional: Incorporate externally developed feature into your feature
Option 1: git cherry-pick <commit>
Option 2: git merge [commit] [branch]
Option 3: git rebase -i <new-base>
Perform tests as needed throughout development process, but at a minimum before you submit a pull request.
git push ACME-Climate/ACME github-username/component/feature
(push to the shared repository on github)Visit http://github.com/ACME-Climate/ACME and submit a pull request to ACME/master
...
Before communicating with remotes, you might want to add or remove remotes. In order to add and remove remotes the git remote command can be used. The two uses are as follows:
git remote add remote-name protocol:address/to/repo # Creates a remote
git remote remove remote-name # Removes a remote
In order to communicate with remotes, there are three actions. push, pull, and fetch.
...