collab:git-usage
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
collab:git-usage [2012/12/13 10:46] c7031007 |
collab:git-usage [2016/02/28 11:25] c7031007 |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| Please follow these simple guidelines to help everybody get the most out of revision control: | Please follow these simple guidelines to help everybody get the most out of revision control: | ||
| - | * **No auto-generated files** should be added to the repository. They are unnecessary and may give rise to nasty merge conflicts. | + | * **No auto-generated files** should be added to the repository((Exception: files whose auto-generation requires tools that you cannot trivially expect all contributors to install.)). They are unnecessary and may give rise to nasty merge conflicts. Consider adding a ''Makefile'' or scripts for auto-generating files where their making is not obvious. |
| - | * To help with the previous point, consider adding a ''Makefile'' or scripts for auto-generating files where their making is not obvious. | + | |
| * Use **''.gitignore''** files to keep the workspace clean for ''git status'' and friends. List all auto-generated files, including backup files, in ''.gitignore''. Likewise for Subversion, use ''svn propedit svn:ignore //directory//''. | * Use **''.gitignore''** files to keep the workspace clean for ''git status'' and friends. List all auto-generated files, including backup files, in ''.gitignore''. Likewise for Subversion, use ''svn propedit svn:ignore //directory//''. | ||
| - | * With each commit, include only a **single, self-contained type of change** (which will often include changes to multiple files). Keep this change minimal to make it easy to follow edits with ''git log'', ''annotate'', ''diff'' etc. For example, confine content changes and formatting changes to separate commits. | + | * With each commit, include only a **single, self-contained type of change** (which will often include changes to multiple files). Keep each change minimal to make it easy to follow edits with ''git log'', ''annotate'', ''diff'' etc. For example, confine content changes and formatting changes to separate commits. |
| - | * To help with the previous point, it is most useful to use hard linebreaks instead of one-line paragraphs because it makes local changes easier to spot. Take care to alter as few lines as possible; do not reflow paragraphs if your edits affect only isolated lines. If the formatting becomes ugly, commit separate formatting-only edits. | + | * Commit, **push and pull frequently**. This will help avoid merge conflicts that need to be fixed by hand. |
| - | * Provide a brief but **informative message** with each commit. (This should go without saying.) | + | * To make changes easy to spot, it is most useful to **use hard linebreaks instead of one-line paragraphs**. **Avoid altering unaffected lines**; do not reflow paragraphs if your edits affect only isolated lines. If the formatting becomes ugly, commit separate formatting-only edits. |
| + | * Provide a brief but **informative message** with each commit. | ||
| * Do not keep multiple versions of files in the repository. The repository does this automatically for you. | * Do not keep multiple versions of files in the repository. The repository does this automatically for you. | ||
| - | * Keep the repository **self-contained**, or include easy-to-follow instructions of how to obtain any required extra material. This is particularly an issue with BibTeX files. For %%IIS%%-internal documents, the recommended solution is to cite only publications from [[@/iis/viewgit/index.php?a=summary&p=iisbib|IISbib]] using ''\bibliography{iisbib,otherbib}'', which can then simply be accessed via symbolic links to the respective ''.bib'' files in ''iisbib/exports/''. For externally-shared documents, the recommended solution is the inclusion of a custom ''.bib'' file in the repository together with the paper, using [[http://tex.stackexchange.com/questions/417/how-to-split-all-bibtex-referenced-entries-from-a-big-bibtex-database-to-a-copy|automatic tools to feed it cited references from external BibTeX databases]]((Justus has no personal experience with such tools. If you have more specific recommendations, please document them here. We could also quite easily roll or own mechanism for use with IISbib.)). | + | * Keep the repository **self-contained**, or include easy-to-follow instructions of how to obtain any required extra material. This is particularly an issue with BibTeX files. For %%IIS%%-internal documents, the recommended solution is to only cite publications from [[@/iis/viewgit/index.php?a=summary&p=iisbib|IISbib]] using ''\bibliography{iisbib,otherbib}'', which can then simply be accessed via symbolic links to the respective ''.bib'' files in ''iisbib/exports/''. For externally-shared documents, the recommended solution is the inclusion of a custom ''.bib'' file in the repository together with the paper, using [[http://tex.stackexchange.com/questions/417/how-to-split-all-bibtex-referenced-entries-from-a-big-bibtex-database-to-a-copy|automatic tools to feed it cited references from external BibTeX databases]]((Justus has no personal experience with such tools. If you have more specific recommendations, please document them here. We could also quite easily roll our own mechanism for use with IISbib.)). |
collab/git-usage.txt · Last modified: 2018/09/03 19:35 (external edit)