Mercurial > hgbook
comparison en/ch04-daily.xml @ 811:a66f6d499afa
Add paragraph IDs
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri, 24 Apr 2009 00:27:21 -0700 |
parents | 1a0a78e197c3 |
children | 6b7818eb3d8e |
comparison
equal
deleted
inserted
replaced
810:1a0a78e197c3 | 811:a66f6d499afa |
---|---|
675 </sect1> | 675 </sect1> |
676 | 676 |
677 <sect1> | 677 <sect1> |
678 <title>More useful diffs</title> | 678 <title>More useful diffs</title> |
679 | 679 |
680 <para>The default output of the <command role="hg-cmd">hg | 680 <para id="x_6c7">The default output of the <command role="hg-cmd">hg |
681 diff</command> command is backwards compatible with the | 681 diff</command> command is backwards compatible with the |
682 regular <command>diff</command> command, but this has some | 682 regular <command>diff</command> command, but this has some |
683 drawbacks.</para> | 683 drawbacks.</para> |
684 | 684 |
685 <para>Consider the case where we use <command role="hg-cmd">hg | 685 <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg |
686 rename</command> to rename a file.</para> | 686 rename</command> to rename a file.</para> |
687 | 687 |
688 &interaction.ch04-diff.rename.basic; | 688 &interaction.ch04-diff.rename.basic; |
689 | 689 |
690 <para>The output of <command role="hg-cmd">hg diff</command> above | 690 <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above |
691 obscures the fact that we simply renamed a file. The <command | 691 obscures the fact that we simply renamed a file. The <command |
692 role="hg-cmd">hg diff</command> command accepts an option, | 692 role="hg-cmd">hg diff</command> command accepts an option, |
693 <option>--git</option> or <option>-g</option>, to use a newer | 693 <option>--git</option> or <option>-g</option>, to use a newer |
694 diff format that displays such information in a more readable | 694 diff format that displays such information in a more readable |
695 form.</para> | 695 form.</para> |
696 | 696 |
697 &interaction.ch04-diff.rename.git; | 697 &interaction.ch04-diff.rename.git; |
698 | 698 |
699 <para>This option also helps with a case that can otherwise be | 699 <para id="x_6ca">This option also helps with a case that can otherwise be |
700 confusing: a file that appears to be modified according to | 700 confusing: a file that appears to be modified according to |
701 <command role="hg-cmd">hg status</command>, but for which | 701 <command role="hg-cmd">hg status</command>, but for which |
702 <command role="hg-cmd">hg diff</command> prints nothing. This | 702 <command role="hg-cmd">hg diff</command> prints nothing. This |
703 situation can arise if we change the file's execute | 703 situation can arise if we change the file's execute |
704 permissions.</para> | 704 permissions.</para> |
705 | 705 |
706 &interaction.ch04-diff.chmod; | 706 &interaction.ch04-diff.chmod; |
707 | 707 |
708 <para>The normal <command>diff</command> command pays no attention | 708 <para id="x_6cb">The normal <command>diff</command> command pays no attention |
709 to file permissions, which is why <command role="hg-cmd">hg | 709 to file permissions, which is why <command role="hg-cmd">hg |
710 diff</command> prints nothing by default. If we supply it | 710 diff</command> prints nothing by default. If we supply it |
711 with the <option>-g</option> option, it tells us what really | 711 with the <option>-g</option> option, it tells us what really |
712 happened.</para> | 712 happened.</para> |
713 | 713 |
715 </sect1> | 715 </sect1> |
716 | 716 |
717 <sect1> | 717 <sect1> |
718 <title>Which files to manage, and which to avoid</title> | 718 <title>Which files to manage, and which to avoid</title> |
719 | 719 |
720 <para>Revision control systems are generally best at managing text | 720 <para id="x_6cc">Revision control systems are generally best at managing text |
721 files that are written by humans, such as source code, where the | 721 files that are written by humans, such as source code, where the |
722 files do not change much from one revision to the next. Some | 722 files do not change much from one revision to the next. Some |
723 centralized revision control systems can also deal tolerably | 723 centralized revision control systems can also deal tolerably |
724 well with binary files, such as bitmap images.</para> | 724 well with binary files, such as bitmap images.</para> |
725 | 725 |
726 <para>For instance, a game development team will typically manage | 726 <para id="x_6cd">For instance, a game development team will typically manage |
727 both its source code and all of its binary assets (e.g. geometry | 727 both its source code and all of its binary assets (e.g. geometry |
728 data, textures, map layouts) in a revision control | 728 data, textures, map layouts) in a revision control |
729 system.</para> | 729 system.</para> |
730 | 730 |
731 <para>Because it is usually impossible to merge two conflicting | 731 <para id="x_6ce">Because it is usually impossible to merge two conflicting |
732 modifications to a binary file, centralized systems often | 732 modifications to a binary file, centralized systems often |
733 provide a file locking mechanism that allow a user to say | 733 provide a file locking mechanism that allow a user to say |
734 <quote>I am the only person who can edit this | 734 <quote>I am the only person who can edit this |
735 file</quote>.</para> | 735 file</quote>.</para> |
736 | 736 |
737 <para>Compared to a centralized system, a distributed revision | 737 <para id="x_6cf">Compared to a centralized system, a distributed revision |
738 control system changes some of the factors that guide decisions | 738 control system changes some of the factors that guide decisions |
739 over which files to manage and how.</para> | 739 over which files to manage and how.</para> |
740 | 740 |
741 <para>For instance, a distributed revision control system cannot, | 741 <para id="x_6d0">For instance, a distributed revision control system cannot, |
742 by its nature, offer a file locking facility. There is thus no | 742 by its nature, offer a file locking facility. There is thus no |
743 built-in mechanism to prevent two people from making conflicting | 743 built-in mechanism to prevent two people from making conflicting |
744 changes to a binary file. If you have a team where several | 744 changes to a binary file. If you have a team where several |
745 people may be editing binary files frequently, it may not be a | 745 people may be editing binary files frequently, it may not be a |
746 good idea to use Mercurial&emdash;or any other distributed | 746 good idea to use Mercurial&emdash;or any other distributed |
747 revision control system&emdash;to manage those files.</para> | 747 revision control system&emdash;to manage those files.</para> |
748 | 748 |
749 <para>When storing modifications to a file, Mercurial usually | 749 <para id="x_6d1">When storing modifications to a file, Mercurial usually |
750 saves only the differences between the previous and current | 750 saves only the differences between the previous and current |
751 versions of the file. For most text files, this is extremely | 751 versions of the file. For most text files, this is extremely |
752 efficient. However, some files (particularly binary files) are | 752 efficient. However, some files (particularly binary files) are |
753 laid out in such a way that even a small change to a file's | 753 laid out in such a way that even a small change to a file's |
754 logical content results in many or most of the bytes inside the | 754 logical content results in many or most of the bytes inside the |
757 version of a file are always large, Mercurial will not be able | 757 version of a file are always large, Mercurial will not be able |
758 to store the file's revision history very efficiently. This can | 758 to store the file's revision history very efficiently. This can |
759 affect both local storage needs and the amount of time it takes | 759 affect both local storage needs and the amount of time it takes |
760 to clone a repository.</para> | 760 to clone a repository.</para> |
761 | 761 |
762 <para>To get an idea of how this could affect you in practice, | 762 <para id="x_6d2">To get an idea of how this could affect you in practice, |
763 suppose you want to use Mercurial to manage an OpenOffice | 763 suppose you want to use Mercurial to manage an OpenOffice |
764 document. OpenOffice stores documents on disk as compressed zip | 764 document. OpenOffice stores documents on disk as compressed zip |
765 files. Edit even a single letter of your document in OpenOffice, | 765 files. Edit even a single letter of your document in OpenOffice, |
766 and almost every byte in the entire file will change when you | 766 and almost every byte in the entire file will change when you |
767 save it. Now suppose that file is 2MB in size. Because most of | 767 save it. Now suppose that file is 2MB in size. Because most of |
770 from your perspective, perhaps only a few words are changing | 770 from your perspective, perhaps only a few words are changing |
771 each time. A single frequently-edited file that is not friendly | 771 each time. A single frequently-edited file that is not friendly |
772 to Mercurial's storage assumptions can easily have an outsized | 772 to Mercurial's storage assumptions can easily have an outsized |
773 effect on the size of the repository.</para> | 773 effect on the size of the repository.</para> |
774 | 774 |
775 <para>Even worse, if both you and someone else edit the OpenOffice | 775 <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice |
776 document you're working on, there is no useful way to merge your | 776 document you're working on, there is no useful way to merge your |
777 work. In fact, there isn't even a good way to tell what the | 777 work. In fact, there isn't even a good way to tell what the |
778 differences are between your respective changes.</para> | 778 differences are between your respective changes.</para> |
779 | 779 |
780 <para>There are thus a few clear recommendations about specific | 780 <para id="x_6d4">There are thus a few clear recommendations about specific |
781 kinds of files to be very careful with.</para> | 781 kinds of files to be very careful with.</para> |
782 | 782 |
783 <itemizedlist> | 783 <itemizedlist> |
784 <listitem> | 784 <listitem> |
785 <para>Files that are very large and incompressible, e.g. ISO | 785 <para id="x_6d5">Files that are very large and incompressible, e.g. ISO |
786 CD-ROM images, will by virtue of sheer size make clones over | 786 CD-ROM images, will by virtue of sheer size make clones over |
787 a network very slow.</para> | 787 a network very slow.</para> |
788 </listitem> | 788 </listitem> |
789 <listitem> | 789 <listitem> |
790 <para>Files that change a lot from one revision to the next | 790 <para id="x_6d6">Files that change a lot from one revision to the next |
791 may be expensive to store if you edit them frequently, and | 791 may be expensive to store if you edit them frequently, and |
792 conflicts due to concurrent edits may be difficult to | 792 conflicts due to concurrent edits may be difficult to |
793 resolve.</para> | 793 resolve.</para> |
794 </listitem> | 794 </listitem> |
795 </itemizedlist> | 795 </itemizedlist> |
796 </sect1> | 796 </sect1> |
797 | 797 |
798 <sect1> | 798 <sect1> |
799 <title>Backups and mirroring</title> | 799 <title>Backups and mirroring</title> |
800 | 800 |
801 <para>Since Mercurial maintains a complete copy of history in each | 801 <para id="x_6d7">Since Mercurial maintains a complete copy of history in each |
802 clone, everyone who uses Mercurial to collaborate on a project | 802 clone, everyone who uses Mercurial to collaborate on a project |
803 can potentially act as a source of backups in the event of a | 803 can potentially act as a source of backups in the event of a |
804 catastrophe. If a central repository becomes unavailable, you | 804 catastrophe. If a central repository becomes unavailable, you |
805 can construct a replacement simply by cloning a copy of the | 805 can construct a replacement simply by cloning a copy of the |
806 repository from one contributor, and pulling any changes they | 806 repository from one contributor, and pulling any changes they |
807 may not have seen from others.</para> | 807 may not have seen from others.</para> |
808 | 808 |
809 <para>It is simple to use Mercurial to perform off-site backups | 809 <para id="x_6d8">It is simple to use Mercurial to perform off-site backups |
810 and remote mirrors. Set up a periodic job (e.g. via the | 810 and remote mirrors. Set up a periodic job (e.g. via the |
811 <command>cron</command> command) on a remote server to pull | 811 <command>cron</command> command) on a remote server to pull |
812 changes from your master repositories every hour. This will | 812 changes from your master repositories every hour. This will |
813 only be tricky in the unlikely case that the number of master | 813 only be tricky in the unlikely case that the number of master |
814 repositories you maintain changes frequently, in which case | 814 repositories you maintain changes frequently, in which case |
815 you'll need to do a little scripting to refresh the list of | 815 you'll need to do a little scripting to refresh the list of |
816 repositories to back up.</para> | 816 repositories to back up.</para> |
817 | 817 |
818 <para>If you perform traditional backups of your master | 818 <para id="x_6d9">If you perform traditional backups of your master |
819 repositories to tape or disk, and you want to back up a | 819 repositories to tape or disk, and you want to back up a |
820 repository named <filename>myrepo</filename>. Use <command>hg | 820 repository named <filename>myrepo</filename>. Use <command>hg |
821 clone -U myrepo myrepo.bak</command> to create a | 821 clone -U myrepo myrepo.bak</command> to create a |
822 clone of <filename>myrepo</filename> before you start your | 822 clone of <filename>myrepo</filename> before you start your |
823 backups. The <option>-U</option> option doesn't check out a | 823 backups. The <option>-U</option> option doesn't check out a |
824 working directory after the clone completes, since that would be | 824 working directory after the clone completes, since that would be |
825 superfluous and make the backup take longer. | 825 superfluous and make the backup take longer. |
826 | 826 |
827 <para>If you then back up <filename>myrepo.bak</filename> instead | 827 <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead |
828 of <filename>myrepo</filename>, you will be guaranteed to have a | 828 of <filename>myrepo</filename>, you will be guaranteed to have a |
829 consistent snapshot of your repository that won't be pushed to | 829 consistent snapshot of your repository that won't be pushed to |
830 by an insomniac developer in mid-backup.</para> | 830 by an insomniac developer in mid-backup.</para> |
831 </sect1> | 831 </sect1> |
832 </chapter> | 832 </chapter> |