Intelligent and Interactive Systems

User Tools

Site Tools


collab:git-usage

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
collab:git-usage [2012/12/13 09:46]
c7031007 created
collab:git-usage [2018/09/03 19:35] (current)
Line 1: Line 1:
 ======Editing and Committing====== ======Editing and Committing======
  
-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.
  
-  * Do not add auto-generated files to the repository. +=====How ​to Commit===== 
-  * 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''​. +  * 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. 
-  * 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. +  * Commit, **push and pull frequently**. This will help avoid merge conflicts that need to be fixed by hand. 
-  * 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 spotTake 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. +  * 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. ​(This should ​go without saying.)+  * Provide a brief but **informative message** with each commit. 
 +  * 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.)). 
 + 
 +=====What Not to Commit===== 
 + 
 +  * **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. 
 +  * 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//''​. 
 +  * Do not commit **large, binary files** such as videos. Git does not handle these well; ''​git pull''​ can take arbitrarily long((We might look into [[https://​git-annex.branchable.com/​|git-annex]].)). Rather, keep videos on the IIS server; the recommended place for now is ''​iis:/​projects/​www/​public/​videos/''​.
   * 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.
 +
collab/git-usage.1355388407.txt.gz · Last modified: 2018/09/03 14:57 (external edit)