@matheusbsbs / matheus-bagliano / commits / bdd9f4240f
Fork 0

Add a Tips and Tricks section to fast-import's manual.

There has been some informative lessons learned in the gfi user community, and these really should be written down and documented for future generations of frontend developers. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

Shawn O. Pearce committed Feb 7, 2007 at 03:49 UTC bdd9f4240f3686ca9beb14d803772995b43f39d5
1 file changed +87
Documentation/git-fast-import.txt
+87
@@ -675,6 +675,92 @@ repository can be loaded into Git through gfi in about 3 hours,
675 explicit checkpointing may not be necessary.
676
677
678 +Tips and Tricks
679 +---------------
680 +The following tips and tricks have been collected from various
681 +users of gfi, and are offered here as suggestions.
682 +
683 +Use One Mark Per Commit
684 +~~~~~~~~~~~~~~~~~~~~~~~
685 +When doing a repository conversion, use a unique mark per commit
686 +(`mark :<n>`) and supply the \--export-marks option on the command
687 +line. gfi will dump a file which lists every mark and the Git
688 +object SHA-1 that corresponds to it. If the frontend can tie
689 +the marks back to the source repository, it is easy to verify the
690 +accuracy and completeness of the import by comparing each Git
691 +commit to the corresponding source revision.
692 +
693 +Coming from a system such as Perforce or Subversion this should be
694 +quite simple, as the gfi mark can also be the Perforce changeset
695 +number or the Subversion revision number.
696 +
697 +Freely Skip Around Branches
698 +~~~~~~~~~~~~~~~~~~~~~~~~~~~
699 +Don't bother trying to optimize the frontend to stick to one branch
700 +at a time during an import. Although doing so might be slightly
701 +faster for gfi, it tends to increase the complexity of the frontend
702 +code considerably.
703 +
704 +The branch LRU builtin to gfi tends to behave very well, and the
705 +cost of activating an inactive branch is so low that bouncing around
706 +between branches has virtually no impact on import performance.
707 +
708 +Use Tag Fixup Branches
709 +~~~~~~~~~~~~~~~~~~~~~~
710 +Some other SCM systems let the user create a tag from multiple
711 +files which are not from the same commit/changeset. Or to create
712 +tags which are a subset of the files available in the repository.
713 +
714 +Importing these tags as-is in Git is impossible without making at
715 +least one commit which ``fixes up'' the files to match the content
716 +of the tag. Use gfi's `reset` command to reset a dummy branch
717 +outside of your normal branch space to the base commit for the tag,
718 +then commit one or more file fixup commits, and finally tag the
719 +dummy branch.
720 +
721 +For example since all normal branches are stored under `refs/heads/`
722 +name the tag fixup branch `TAG_FIXUP`. This way it is impossible for
723 +the fixup branch used by the importer to have namespace conflicts
724 +with real branches imported from the source (the name `TAG_FIXUP`
725 +is not `refs/heads/TAG_FIXUP`).
726 +
727 +When committing fixups, consider using `merge` to connect the
728 +commit(s) which are supplying file revisions to the fixup branch.
729 +Doing so will allow tools such as gitlink:git-blame[1] to track
730 +through the real commit history and properly annotate the source
731 +files.
732 +
733 +After gfi terminates the frontend will need to do `rm .git/TAG_FIXUP`
734 +to remove the dummy branch.
735 +
736 +Import Now, Repack Later
737 +~~~~~~~~~~~~~~~~~~~~~~~~
738 +As soon as gfi completes the Git repository is completely valid
739 +and ready for use. Typicallly this takes only a very short time,
740 +even for considerably large projects (100,000+ commits).
741 +
742 +However repacking the repository is necessary to improve data
743 +locality and access performance. It can also take hours on extremely
744 +large projects (especially if -f and a large \--window parameter is
745 +used). Since repacking is safe to run alongside readers and writers,
746 +run the repack in the background and let it finish when it finishes.
747 +There is no reason to wait to explore your new Git project!
748 +
749 +If you choose to wait for the repack, don't try to run benchmarks
750 +or performance tests until repacking is completed. gfi outputs
751 +suboptimal packfiles that are simply never seen in real use
752 +situations.
753 +
754 +Repacking Historical Data
755 +~~~~~~~~~~~~~~~~~~~~~~~~~
756 +If you are repacking very old imported data (e.g. older than the
757 +last year), consider expending some extra CPU time and supplying
758 +\--window=50 (or higher) when you run gitlink:git-repack[1].
759 +This will take longer, but will also produce a smaller packfile.
760 +You only need to expend the effort once, and everyone using your
761 +project will benefit from the smaller repository.
762 +
763 +
764 Packfile Optimization
765 ---------------------
766 When packing a blob gfi always attempts to deltify against the last
@@ -705,6 +791,7 @@ deltas are suboptimal (see above) then also adding the `-f` option
791 to force recomputation of all deltas can significantly reduce the
792 final packfile size (30-50% smaller can be quite typical).
793
794 +
795 Memory Utilization
796 ------------------
797 There are a number of factors which affect how much memory gfi